To comment or not to comment
During our holiday week, we had a task to read a chapter of a book and summarize it. I chose a book called “Code complete”. As indicated in the title, the book focuses on coding. It focused precisely on the many different stages of coding. The book was quite long, 855 pages, so if you were to read the whole book, you would know all about coding and software development. Of course I didn’t have the time to read the whole book, but I chose a single chapter that interested me. The chapter was called “to comment or not to comment”. The chapter was presented as a dialogue, where philosophers discussed whether or not code comments are useful.
The arguments against it were that comments make the code harder to read due to the additional text. A good code should also be self-documenting and not require additional explanation. Others argued that comments make the code easier to read, especially if it’s someone else’s code. I totally agree that comments make the code easier to read, but it’s probably due to the fact that I'm still just a beginner. Even though I find code comments useful, I don’t usually comment my own code. I’ve been trying to change that habit, since sometimes I forget what some of the lines in my code do. I sometimes find myself spending a lot of time just trying to understand my own code, when all that could have been saved with a single comment.
In some cases, commenting might actually make the code confusing if not done properly. The book had a whole different chapter that covered this topic, but I ran out of time to read it. I’ve had experiences though, where a comment actually slowed me down instead of helped me to understand the code. I remember spending more time trying to understand the comment rather than the code itself.
The advice that mostly stuck with me from the chapter is that comments don’t repeat the code or explain it, they clarify its intent. Comments are easier to write poorly than well, and so they can also be more damaging than helpful. But if done correctly, comments can be a huge help and save loads of time. I encourage everyone to comment on their code, including myself, but please, make sure the comments are clear and understandable.
I do suggest the book for anyone who’s interested in coding, since it gives some really great tips on coding in general. I might come back to the book if I ever encounter a situation where I want to deeply understand something about coding or software development.
Your reflection on the chapter from Code Complete is insightful and well-articulated! I really like how you present both sides of the argument about commenting in code, especially with your personal experiences as a beginner. The way you emphasize that comments should clarify intent rather than just repeat the code is a valuable takeaway. Your honesty about struggling with understanding your own code and working on improving your habits makes this piece relatable. Great job on making the topic engaging and encouraging good coding practices! Keep up the great work!
VastaaPoista"Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live." Your post reminded me of this quote. I think it’s not about commenting itself but rather the clarity of code. If it is straightforward and self-explanatory then I would say, there’s no need to comment. But there are times when comments might be crucial for other people to understand what you had in mind while writing the piece of code.
VastaaPoistaGreat post! Code Complete sounds like a really informative book. I like the takeaway that comments should clarify intent rather than just repeat the code.
VastaaPoistaI totally relate to your thoughts on commenting code – as a beginner, I also find comments really helpful, but I sometimes forget to add them myself! It’s great that you’re trying to improve this habit. I agree that comments should clarify the intent, not just repeat the code. I’ll definitely keep that advice in mind for my own coding. Thanks for sharing!
VastaaPoistaHonestly speaking, we are all too lazy to add comments to our code. And we often get confused what have we done on that section. I start start adding comments.
VastaaPoistaInteresting take on code comments. I agree that they can be helpful but also confusing if done poorly. Your point about comments clarifying intent rather than repeating code is a good reminder.
VastaaPoista