It’s Monday again and as usual I’ll be putting my thoughts out there on a specific topic. As you can tell from the title I’m going to attempt to explain why web-developers need to remember to comment their code. This comes from my experience when taking over on projects started and maintained by someone else which I am tasked with after their departure. Three simple reason you need to comment your code are the following:

1. It allows a developer, at a glance, to look at a piece of code and know why it exists.
2. It reduces situations where a piece of codes original intent isn’t clear then gets modified and leads to unintended regressions.
3. It reduces the amount of context a developer must hold his/her mind to solve any particular problem that may be contained in a piece of code.

Here is a minimal list of what you should do

1. Never name your classes and functions ambiguously.
2. Always use inline comments on code blocks that are complicated or may appear unclear.
3. Always use descriptive variable names.
4. Always write comments describing the intent or reason why a piece of code exists.
5. Always keep comments up to date when editing commented code.
6. Write comments in English. If you are Greek or Afrikaans I will be able to read your comments but if you write comments in other languages, they are useless to me. This assumes you know the languages I speak which you may not. So please always use English. You never know who might need to read and interpret your code.

If you have any questions, feel free to email info@georgenicolaou.me