A checklist for building Java + Angular/React web applications in the correct way
Switch branches/tags
Nothing to show
Latest commit abd69c4 Aug 11, 2017 @shekhargulati added few more quotes
Permalink
Failed to load latest commit information.
LICENSE Initial commit Aug 8, 2017
README.md added few more quotes Aug 10, 2017

README.md

building-java-web-apps-checklist

This repository shares a checklist that I use for building web applications in Java+ Angular/React.

🔰 Before you start development

Software architecture is the set of design decisions which, if made incorrectly, may cause your project to be cancelled. — Eoin Woods

  • Take architectural decisions. Finalize tech stack.
  • 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 for inspiration. backend contains Java code of the application. frontend contains all React/Angular JavaScript/TypeScript code of the application.
  • You should use Maven or Gradle wrapper scripts so that a new developer do not need to install Maven or Gradle on their machine before executing the build.
  • 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.
  • Set up CI server and make sure it can build the project as a single executable.
  • Fix standup time and make sure it works for everyone.
  • Finalise your sprint duration.
  • Finalise your testing strategy both manual and automated.
  • Each team member should come up with their learning goal.

💻 During Development

Git

  • Work on feature branches.
  • Branch out from develop branch.
  • Never push to master or develop. Make a pull request.
  • 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.
  • Delete local and remote branches after merging. You can automate this process as well.
  • Before raising PR, run the build locally and make sure all tests pass.
  • Use .gitignore file.
  • Protect your master branch.
  • Never commit binary files to Git.
  • Write meaningful Git commit messages. Read Chris Beam post on it.
  • Feature branches should be short lived.

Continuous Integration

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

  • Every code committed to version control system mainline should trigger a continuous integration job that runs on the integration server.
  • Continuous integration job should build the project and run all unit test cases. It should happen on each code commit to mainline.
  • Fix broken builds immediately. CI server should always be in healthy green state.
  • Make CI server visible and transparent to whole team.
  • Maintain build jobs as code use Jenkinsfile if you are using Jenkins
  • You should be able to create build jobs on a new CI server using code.
  • Use pull request builder to build the project when pull request is raised.

Documentation

Documentation is the castor oil of programming. Managers think it is good for programmers and programmers hate it!. — Gerald Weinberg

  • Create README.md file in root of your project and keep it updated. The README file should have following:
  • Couple of lines describing purpose of the project.
  • Instruction to grab the latest code and detailed instructions to build it.
  • Instructions to run the project on local machine.
  • Link to Continuous integration server.
  • Instruction to do any setup required for the project.
  • Instruction to grab project documentation.
  • Any other relevant information that can help a new developer get started with the project.

Code Style

Style distinguishes excellence from accomplishment. — James Coplien

  • For backend, use Checkstyle in your project. Make sure you it is integrated with the build.
  • For frontend, use ESLint or TSLint.

Testing

Program testing can be used to show the presence of bugs, but never to show their absence! — Edsger Dijkstra

  • Write one automated functional test per user story.
  • Cover business logic with unit/Integration tests.
  • Understand different between unit testing and integration testing.
  • Use consistent names for tests. I prefer to use *Tests as suffix for my tests.
  • Use consistent naming strategy for tests like shouldRegisterNewUser or registerNewUser or should_register_new_user

Dependencies

  • Add a new dependency to the project after discussing with the team.
  • Use Snyk to check security vulnerabilities.
  • Don't add dependency for each problem you face. First check if you already have some dependency that solves the problem.

Learning

You have to learn the rules of the game. And then you have to play better than anyone else. — Albert Einstein

  • Spend one hour on learning every day.
  • Give session at your office or local meetup.
  • Write blogs.

Naming

There are only two hard things in computer science: Cache Invalidation and Naming Things — Phil Karlton

  • Think and discuss with team before choosing a name for public member.
  • Java and JavaScript use PascalCase for classes, interfaces, enums, annotations.
  • Java and JavaScript use camelCase for methods and variables.

Exception Handling

  • Catch any checked exception thrown by the code.
  • Convert checked exception to unchecked exception.
  • Throw the unchecked exception. Unchecked exception could be custom or plain RuntimeException.
  • Always use two arguments constructor of RuntimeException. The first take a message, second is the actual exception.
  • Catch all exceptions thrown by code in your Controller or Resource classes.
  • Log exceptions only in the Controller or Resource classes.
  • Log both the message and exception. If using slf4j, then use log.error(“message”,e).

Logging

  • Use slf4j with logback for logging.

REST API Design

  • 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.
  • Resources are nouns.
  • Use HTTP POST for creating a resource on the server or for taking action. Always return location of created entity in the Location header.
  • Use PATCH HTTP method for update for partial update.
  • Use PUT HTTP method when you do full update i.e. when client sends all the information in the request.
  • 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.
  • In the above example if you have to implement undo action then you can make HTTP DELETE operation to /api/v1/posts/actions/unlike.
  • For testing RESTful clients, use mock server. Use MockWebServer JUnit rule for testing HTTP interactions.
  • Learn how great REST APIs are designed. I refer to Github REST API when in doubt. I find it the best designed REST API.

Code Review

Code reviews are about code not people. Don't take code criticism personally.

  • Are there any obvious logic errors in the code?
  • Are unit tests written for the business logic?
  • Does all the functional requirements met?
  • Does the code conform to existing style guidelines?
  • Propose better way to do certain tasks. It could be a library function that developer can use.

Front-end

  • Commit yarn.lock file
  • Remove all console.log statements in the code.
  • Use linter and integrate it with the build tool.
  • Make sure there are no warnings and errors in the console.
  • Test on all the four major browsers — Chrome, Firefox, IE, and Safari.
  • Check spellings.
  • Make sure grammar is correct in the messages.
  • Add Google Analytics into your project.
  • Use jQuery 3 instead of earlier versions of jQuery.
  • Prefer Angular 4+ over Angular 1.x.

You can follow me on twitter at https://twitter.com/shekhargulati or email me at shekhargulati84@gmail.com. Also, you can read my blogs at http://shekhargulati.com/