
Comment Your Code with Care - kiyanwang
https://medium.com/gitconnected/comment-your-code-with-care-e355f3de2b34
======
iamNumber4
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

~~~
warlyware
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.

------
mannykannot
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?

~~~
warlyware
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.

