Comment, comment comment. It must been a hell of a side job as a programmer or similar to do. We are programmers, we writes code, not documents, yada yada..
Well, that is what I thought in the first place.
Commenting is very very important in a long term or growing project. No matter how beautiful and readable your ‘self-documenting code’ will be. Why? The key is again, why?
Your code already does what it does, tell the computer to do things, and tell you what it does. However, why the code is even there in the first place? Why?
The first step to make documenting and reading it as a fun thing is, make it tell you why the code is there.
For instance, you have a function that writes to a configuration file on a Linux hosting server with only FTP access without SSH (I know it sucks, consider alternatives including DigitalOcean for VPS-like hosting or Bluehost also Dreamhost for SSH access).
An example comment for this scenario is – the server doesn’t have SSH access to execute Linux commands, so we implement this to write the code invoked from the execution of the web app.
And there ladies and gentleman, will make your life easier by commenting why instead of what.
Don’t repeat the code, assume the audience already understand the language and algorithm, and it is their fault for not taking enough time and effort to understand it (unless you writing clever code and cryptic algorithms, you are to blame instead).
Other keys like enforcing the use of good grammar and simplicity of the commenting language is also important too, but don’t let that stopping you from commenting your code if you are not fluent at the target language.
You are an awesome person for reading this. Why? because you have the passion to look the answer, to be a better developer, thus making your life and others easier to make reading codes and documentations an enjoyable experience.
Protect it, live it, love it, soon it is nothing for you, but a good habit.