Eyes, JAPAN Blog > Good Code Starts Before Coding

Good Code Starts Before Coding



As a programmer, it is too easy to get absorbed into the world of the code too much. We worry about coding style, conventions and the tools we use. But the code isn’t everything in the project.

Before even starting to work, the project itself has to be set up properly. Talks must be had with the stake holders, defining proper specifications and Mockups to tighten the boundaries our solutions can exist within.

JIRA is a very popular solution for project management used in many businesses around the world, us included. Besides tracking issues in JIRA, we also use Confluence to define our specifications and organise other documents in a Wiki style service. This makes editing and updating information very simple.

A few rules for Confluence and JIRA:

  •  Have an overall plan of the project before starting work on it (workflow, UI elements,). Break it down. A mockup goes a long way and makes questions and problems apparent.
  • A JIRA project and board must exist with the correct Workflows and issue types set up.
  • Use the “Project Shortcuts” and “Source Code” links to make it easier finding related documents (e.g. Confluence, Test Server, …)
  • Before touching any code, there must be an issue in JIRA for the work to do.
  • Ensure tickets have proper release versioning and components selected.
  • Keep your issue tickets (important comments, state changes, worked time) and Confluence pages (Graphs and other documents) updated.
  • After resolving a ticket, make a pull request and have another person check and merge or decline it (with commented reason).

If we can be sure that our issues and documentation is in order at all times it is easier to make decisions. What should we work on next? How much time do I have until the release? Do I have the time to spend more time on refactoring or do I have to start working on that bug report?

Once we are set to pick a ticket (usually in the order we prioritised them), we can worry about our code:

  • Use git-flow for source code versioning.
  • More code  but understandable code is better than less code but more cryptic code.
  • As little 3rd party code as possible (If, for example the environment, language or frameworks change you are the mercy of the original dev or need to do lots of work to fix other people’s code).
  • Take care of warnings as soon as possible (to avoid problems later, also easier debugging).
  • Add a README file with overall information (used language, frameworks, include version information with links) to the project and keep it up-to-date.
  • Add comments to your code to explain what it does.
  • If you update/replace code, make sure the comments/documentation are updated as well.
  • Expressive names, e.g.:
  • onPlayButton() instead just play() for a function triggered by a UI Button.
  • temperatureCelcius instead of tmp_c.
  • Document your designs (e.g. Confluence, Graphs, etc.)
  • Tests!
  • Use linters to ensure common code-style (use rules as strict as possible, but as comfortable as necessary).

The most important besides all this pre-written rules is to stay alert. If any problem arises, review those rules and consider changes or additions. If there is a problem during the work on a project, the first priority is to find a way to avoid that particular type of problem to be able to happen again.

  • このエントリーをはてなブックマークに追加