Comment Your Code with Care | Hacker News Reader

Comment Your Code with Care

medium.com

3 pointskiyanwang4 comments

I generally agree to comment with care. However the examples in the article are just bad. As a rule of thumb it is generally accepted that you comment your classes and public methods. You define the inputs and returns, and the general description of the stated purpose of the class/Method/Function. This is basis of your codebase and the available it's associated API.

Code without comments is very bad. There is no such thing as self documenting code. You have to consider who will be making modifications to the code after you, and that your comments sole purpose is to convey the fundamental design of your code.

document the purpose for the code, document the inputs and returns, document the algorithm steps when appropriate. Do not put a comment on every line. Just comment the unclear or potentially fuzzy bits.

also on a side note, if your code is slick and clever and requires a comment to explain it because it is complex and cryptic. You Failed!

Our life is frittered away by detail... simplify, simplify, simplify. --Henry David Thoreau

Thanks for your input on the article! In my my experience and research, it is very difficult to find "a rule of thumb [that] is generally accepted" regarding comments. While commenting on classes and public methods the way you describe is a common practice, my argument is that this is a largely arbitrary method of commenting code that can lead to comments that are not always maintained with the same care as the code it is describing. By only commenting when the code is not self explanatory, and cannot reasonably be refactored so as to make it self explanatory, your code will become easier to read and will be less prone to harboring unmaintained, misleading comments.

And I couldn't agree more with your sentiment regarding code that is so "slick and clever" that it requires comments. Readability is better than slick and clever any day of the week.

Articles like this show up so frequently that you might think that excessive commenting is the major problem afflicting software development. If it is, I have somehow not run into it.

What's more, the articles are all the same, echoing one another with nary a new insight. The only issue of interest here is why so many developers choose this issue to redundantly blog about. Is it a starter topic to get some practice on, before advancing to other, more technical shibboleths, such as the awful inexpressiveness of statically-typed languages?

Thank you for your feedback on the article! I am glad to hear this has not been a problem in your development career, but I cannot say the same for myself. Conversations revolving around when code should be commented vs. refactored are commonplace among a number of my coworker.

I expect articles on this topic are common because it is a problem faced by developers of any language, and the opinions on the topic actually differ quite a bit from author to author. And while I admit I am far from a seasoned veteran in tech blogging, the contentiousness of the subject made me weary about choosing it for an early topic in my blogging career. However, how and when we comment code struck me as an interesting topic that I have opinions on, and which I hadn't seen expressed in the way I attempted to say them.

My goal is to share my thoughts with other developers, so that dialogs are opened, and so that we can all benefit from openly sharing our opinions.

Reply on news.ycombinator.com