├── LICENSE └── README.md /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2017 Shekhar Gulati 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # ✅ building-java-web-apps-checklist ![](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat) 2 | 3 | This repository shares a checklist that I use for building web applications in Java+ Angular/React. 4 | 5 | ## :beginner: Before you start development 6 | 7 | > ***Software architecture is the set of design decisions which, if made incorrectly, may cause your project to be cancelled. — Eoin Woods*** 8 | 9 | - [ ] Take architectural decisions. Finalize tech stack. 10 | - [ ] Create a multi-module Maven or Gradle project for your development. Start with two modules — `backend` and `frontend`. You can refer to [spring-boot-react-maven-starter](https://github.com/shekhargulati/spring-boot-react-maven-starter) for inspiration. `backend` contains Java code of the application. `frontend` contains all React/Angular JavaScript/TypeScript code of the application. 11 | - [ ] You should use [Maven](https://github.com/takari/maven-wrapper) or [Gradle](https://docs.gradle.org/current/userguide/gradle_wrapper.html) wrapper scripts so that a new developer do not need to install Maven or Gradle on their machine before executing the build. 12 | - [ ] Build project as a single jar/war using a single command i.e. if I am using Maven as my build tool then I should be able to run `./mvnw clean install` in the project root to build the executable. 13 | - [ ] Set up CI server and make sure it can build the project as a single executable. 14 | - [ ] Fix standup time and make sure it works for everyone. 15 | - [ ] Finalise your sprint duration. 16 | - [ ] Finalise your testing strategy both manual and automated. 17 | - [ ] Each team member should come up with their learning goal. 18 | 19 | ## :computer: During Development 20 | 21 | ### [Git](https://www.atlassian.com/git) 22 | 23 | - [ ] Work on feature branches. 24 | - [ ] Branch out from `develop` branch. 25 | - [ ] Never push to `master` or `develop`. Make a pull request. 26 | - [ ] Create PR on the `develop` branch and once it is tested then only merge to master. You can use different strategy like merge to `master` once sprint finishes. 27 | - [ ] Delete local and remote branches after merging. You can automate this process as well. 28 | - [ ] Before raising PR, run the build locally and make sure all tests pass. 29 | - [ ] Use `.gitignore` file. 30 | - [ ] Protect your `master` branch. 31 | - [ ] Never commit binary files to Git. 32 | - [ ] Write meaningful Git commit messages. [Read Chris Beam post on it](https://chris.beams.io/posts/git-commit/). 33 | - [ ] Feature branches should be short lived. 34 | 35 | ### [Continuous Integration](https://martinfowler.com/articles/continuousIntegration.html) 36 | 37 | > ***The most important practice for continuous integration to work properly is frequent check-ins to trunk or mainline. You should be checking in your code at least a couple of times a day. — David Farley*** 38 | 39 | - [ ] Every code committed to version control system mainline should trigger a continuous integration job that runs on the integration server. 40 | - [ ] Continuous integration job should build the project and run all unit test cases. It should happen on each code commit to mainline. 41 | - [ ] Fix broken builds immediately. CI server should always be in healthy green state. 42 | - [ ] Make CI server visible and transparent to whole team. 43 | - [ ] Maintain build jobs as code use `Jenkinsfile` if you are using Jenkins 44 | - [ ] You should be able to create build jobs on a new CI server using code. 45 | - [ ] Use pull request builder to build the project when pull request is raised. 46 | 47 | 48 | ### [Documentation](https://robots.thoughtbot.com/how-to-write-a-great-readme) 49 | 50 | > ***Documentation is the castor oil of programming. Managers think it is good for programmers and programmers hate it!. — Gerald Weinberg*** 51 | 52 | - [ ] Create `README.md` file in root of your project and keep it updated. The README file should have following: 53 | - [ ] Couple of lines describing purpose of the project. 54 | - [ ] Instruction to grab the latest code and detailed instructions to build it. 55 | - [ ] Instructions to run the project on local machine. 56 | - [ ] Link to Continuous integration server. 57 | - [ ] Instruction to do any setup required for the project. 58 | - [ ] Instruction to grab project documentation. 59 | - [ ] Any other relevant information that can help a new developer get started with the project. 60 | 61 | ### Code Style 62 | 63 | > ***Style distinguishes excellence from accomplishment. — James Coplien*** 64 | 65 | - [ ] For backend, use [Checkstyle](http://checkstyle.sourceforge.net/) in your project. Make sure you it is integrated with the build. 66 | - [ ] For frontend, use ESLint or [TSLint](https://palantir.github.io/tslint/). 67 | - [ ] Format your code before committing. 68 | 69 | ### Testing 70 | 71 | > ***Program testing can be used to show the presence of bugs, but never to show their absence! — Edsger Dijkstra*** 72 | 73 | - [ ] Write one automated functional test per user story. 74 | - [ ] Cover business logic with unit/Integration tests. 75 | - [ ] Understand different between unit testing and integration testing. 76 | - [ ] Use consistent names for tests. I prefer to use `*Tests` as suffix for my tests. 77 | - [ ] Use consistent naming strategy for tests like `shouldRegisterNewUser` or `registerNewUser` or `should_register_new_user` 78 | 79 | ### Dependencies 80 | 81 | - [ ] Add a new dependency to the project after discussing with the team. 82 | - [ ] Use [Snyk](https://snyk.io/) to check security vulnerabilities. 83 | - [ ] Don't add dependency for each problem you face. First check if you already have some dependency that solves the problem. 84 | 85 | ### Learning 86 | 87 | > ***You have to learn the rules of the game. And then you have to play better than anyone else. — Albert Einstein*** 88 | 89 | - [ ] Spend one hour on learning every day. 90 | - [ ] Give session at your office or local meetup. 91 | - [ ] Write blogs. 92 | 93 | ### Naming 94 | 95 | > ***There are only two hard things in computer science: Cache Invalidation and Naming Things — Phil Karlton*** 96 | 97 | - [ ] Think and discuss with team before choosing a name for public member. 98 | - [ ] Java and JavaScript use PascalCase for classes, interfaces, enums, annotations. 99 | - [ ] Java and JavaScript use camelCase for methods and variables. 100 | 101 | ### Exception Handling 102 | 103 | - [ ] Catch any checked exception thrown by the code. 104 | - [ ] Convert checked exception to unchecked exception. 105 | - [ ] Throw the unchecked exception. Unchecked exception could be custom or plain RuntimeException. 106 | - [ ] Always use two arguments constructor of RuntimeException. The first take a message, second is the actual exception. 107 | - [ ] Catch all exceptions thrown by code in your Controller or Resource classes. 108 | - [ ] Log exceptions only in the Controller or Resource classes. 109 | - [ ] Log both the message and exception. If using slf4j, then use `log.error(“message”,e)`. 110 | 111 | ### Logging 112 | - [ ] Use slf4j with logback for logging. 113 | - [ ] My applications logs all errors 114 | - [ ] The log files are rotated 115 | 116 | ### REST API Design 117 | 118 | - [ ] Pick a versioning strategy. If you don't understand pros and cons of different strategies then pick URL versioning scheme `/api/v1`. Twitter uses this versioning scheme. 119 | - [ ] Resources are nouns. 120 | - [ ] Use HTTP `POST` for creating a resource on the server or for taking action. Always return location of created entity in the `Location` header. 121 | - [ ] Use `PATCH` HTTP method for update for partial update. 122 | - [ ] Use `PUT` HTTP method when you do full update i.e. when client sends all the information in the request. 123 | - [ ] Use `DELETE` HTTP method to delete a resource on the server 124 | - [ ] For mapping actions use a consistent strategy. I recommend using `resource_name/actions/:action` strategy. For example, REST API for implementing `like` functionality you will make HTTP POST request to `/api/v1/posts/123/actions/like` URL. 125 | - [ ] In the above example if you have to implement undo action then you can make HTTP DELETE operation to `/api/v1/posts/actions/unlike`. 126 | - [ ] For testing RESTful clients, use mock server. Use [MockWebServer](https://github.com/square/okhttp/tree/master/mockwebserver) JUnit rule for testing HTTP interactions. 127 | - [ ] Learn how great REST APIs are designed. I refer to [Github REST API](https://developer.github.com/v3/) when in doubt. I find it the best designed REST API. 128 | 129 | ### [Code Review](https://www.atlassian.com/agile/code-reviews) 130 | 131 | > ***Code reviews are about code not people. Don't take code criticism personally.*** 132 | 133 | - [ ] Are there any obvious logic errors in the code? 134 | - [ ] Are unit tests written for the business logic? 135 | - [ ] Does all the functional requirements met? 136 | - [ ] Does the code conform to existing style guidelines? 137 | - [ ] Propose better way to do certain tasks. It could be a library function that developer can use. 138 | 139 | ## Front-end 140 | 141 | - [ ] Commit `yarn.lock` file 142 | - [ ] Remove all `console.log` statements in the code. 143 | - [ ] Use linter and integrate it with the build tool. 144 | - [ ] Make sure there are no warnings and errors in the console. 145 | - [ ] Test on all the four major browsers — Chrome, Firefox, IE, and Safari. 146 | - [ ] Check spellings. 147 | - [ ] Make sure grammar is correct in the messages. 148 | - [ ] Add Google Analytics into your project. 149 | - [ ] Use jQuery 3 instead of earlier versions of jQuery. 150 | - [ ] Prefer Angular 4+ over Angular 1.x. 151 | - [ ] Don't use Bower. Use npm to manage client side dependencies. 152 | 153 | ## Website performance optimization 154 | 155 | - [ ] Run [Lighthouse](https://developers.google.com/web/tools/lighthouse/) tool on your website. 156 | - [ ] Go through [BrowserDiet](https://browserdiet.com/en/) guide. 157 | - [ ] All my application web pages load under 3 seconds. 158 | 159 | ## License 160 | 161 | - [ ] Make sure you do not violate 3rd-party dependencies licenses. Your can use [LicenseFinder](https://github.com/pivotal/LicenseFinder) to compare licenses against a user-defined whitelist. 162 | 163 | ----------- 164 | You can follow me on twitter at [https://twitter.com/shekhargulati](https://twitter.com/shekhargulati) or email me at . Also, you can read my blogs at [http://shekhargulati.com/](http://shekhargulati.com/) 165 | --------------------------------------------------------------------------------