Code Writing Standards - BA-Development-Team/Public_Data GitHub Wiki

We need to develop a guide on several parameters of how we create code - and then follow that as a team.

Our procedure for commenting code. Where, How, How much. Is there a ratio? Which comments are unnecessary?

How does that work with outside technical documentation. We need a plan of what goes into the code comments - and what goes into the function guide. I want our procedure to be that when anything is made - when the developer is working on a specific function - he/she will both comment the code - and also create a page entry for that function/feature/interface and whats happening on it on a broader level. As well as the decisions they took in its writing. (We may need a separate guide for creating function specific technical documentation.)

We also need notes on:

  • Avoiding deep nesting.
  • How we indent our code - and we should be consistent for the whole team.
  • Do we do code grouping - for specific functions in the code?
  • Should there be limits to the horizontal lenght of a line of code.
  • What should we do with temporary names?
  • SQL?
  • Separation of PHP and HTML
  • Others stuff that I dont even know about as a non-developer?

= Can we use an automatic format checker? Can one be configured to our needs?

What I read about this here - but there is more http://net.tutsplus.com/tutorials/html-css-techniques/top-15-best-practices-for-writing-super-readable-code/

Peer Review

We also need to develope a procedure for peer review of code by another team member after development is done. This needs to be scheduled regularly, so while QA begins, another developer needs to take out an hour to go over the new code and outside documentations. Notes should be made on unclear commenting, bad formatting, and the outside documentation. We can also use people from QA for this - as they are not checking the code itself - but - if its comments and documentation are commonsense and can be understood by an outsider.

Rough Draft by Alex:

Commenting

  1. Ensure readability of your code by giving meaningful names to all the variables, classes and functions. Replace unnecessary comments by interpretative names.

    Correct: $gameTitle = "Quiz";

    Incorrect: $gt = "Quiz" // game title

  2. Comment on every piece of your code with a specific functionality, which may be unclear for another developers.

  3. Try to comment it short - few words is the best; one line is the maximum, but make sure that the comment is clear; if you need more space to explain the idea properly, use it.

  4. When writing a new big function/feature/interface, create a page entry, explaining inputs, output, and processes going inside the code. The minimum length for the page entry is two lines.

  5. When submitting a commit to the GitHub, always write a short summary of changes.

  6. After submitting a new piece of code, make sure to have one person to peer review it and give you the feedback on its readability.

Peer Reviewing

Peer Reviewing is necessary for every new piece of code. For every development task, you will be assigned a peer reviewer. When you complete the code and upload it to he GitHub, you should notify your peer reviewer and wait for his/her feedback; then, make all the necessary corrections.

"notes on" (my comments):

  • Avoiding deep nesting.

The basic rule should be "If you have more than 3 levels of nesting, try to rewrite your code in some other way"

  • How we indent our code - and we should be consistent for the whole team.

4 for PHP, 2 for HTML is good

  • Do we do code grouping - for specific functions in the code?

"Separate different blocks of code by empty lines and comments for better visualisation."

  • Should there be limits to the horizontal lenght of a line of code.

"Avoid writing horizontally long lines. Split them so neither piece is standing out from the code"

  • What should we do with temporary names?
  • SQL?
  • Separation of PHP and HTML
  • Others stuff that I dont even know about as a non-developer?