I remember when I was 16 and I started writing my first web application (actually just a simple PHP page that processed some inputs from a form) in PHP. I didn’t really know PHP at all, I have started reading some basic tutorials and then sat down to put in practice what I just learned. I have been familiar with pascal at that time, so I knew how to achieve what I wanted, but I didn’t know the PHP statements, so after finding the right statement I have added a line comment after it, so that I would know what it does. My code was really ugly, but at that time I have found comments quite useful.
But that was a long time ago… Now I hardly write any comments in my code. By the time I’ve got seriously into programming, I’ve learned to comment only those sections that would be really hard to understand for somebody who is not familiar with my style. This was sort of OK until I have met Ruby.
I have worked 9 months in Ruby and I really liked its philosophy, that programming should feel natural and the code must be easy to understand without commenting each line. It should feel like when you learn a language and you communicate using that language. You don’t tell a sentence in German for instance and then tell another 2-3 sentences in English just to explain what you initially wanted to say. If you think your sentence is hard to be understood, then rephrase it, make it more simple. That is what we, developers should do. While working in Ruby, I tried to respect Sandi Metz’ 4 rules, which helped me a lot to write easily understandable code without filling it with unnecessary comments.
And I keep practising it, even after getting back to Java. My solution is rarely perfect for the first time, but I imagine my code as something that lives, something that constantly evolves and it is not that hard to get it in a state in which it is readable and very easy to understand. I often take a break before a commit, I simply lay back to take a look at my code, to enjoy the result of my work. This is the time when I check if there is anything I could do to make it better, more simple. I do care about deadlines and trying to complete my task to respect the estimated hours, but I would rather spend a few extra hours on refactoring to make my solution less complex and allow easy modifications in the future.
I also dislike when the name of a parameter / constant or function name is used in the comment, since it can be a pain in the ass when it comes to refactoring. Refactoring the code feels natural, but modifying the comments to contain the right variable/method name just doesn’t feel right.
I strongly believe that instead of writing comments one should make his/her code more simple by doing a little clean-up and refactoring before committing. If you give your variables and methods meaningful names and if you don’t try to put all your logic in a single method, your code will be easily understandable even without any comments. Oh… and when you think about the cases when you need to comment your code, I bet 90% of them are when you make hacks…