DEV Community

Cover image for Clean Code (Comment)
Elliot Anderson
Elliot Anderson

Posted on

Clean Code (Comment)

Image description

clean code like an art or play an instrument.

dirty code it's bring you to a conclusion in short time.
but when your software enters in the market and users use your software you confront with huge amount of bugs and in is that time your code (complexity + dependency) equal to bankruptcy of a business or a group or company.

your code must be tell your program story

generally comments the less the better.
when a person write comment for any class, function and etc
he knows better then anyone, he's code is dumb and over time, he realizes this amount of confusion and frequent turns in his code.

even write comment has rules you can't write any comment you like.

Some good comments

Legal Comments

Sometimes our corporate coding standards force us to write certain comments for legal
reasons. For example, copyright and authorship statements are necessary and reasonable
things to put into a comment at the start of each source file.

Clarification

Sometimes it is just helpful to translate the meaning of some obscure argument or return
value into something that’s readable. In general it is better to find a way to make that argu-
ment or return value clear in its own right; but when its part of the standard library, or in
code that you cannot alter, then a helpful clarifying comment can be useful.

TODO Comments

t is sometimes reasonable to leave “To do” notes in the form of //TODO comments. In the
following case, the TODO comment explains why the function has a degenerate implementa-
tion and what that function’s future should be.

Some bad comments

Mumbling

Plopping in a comment just because you feel you should or because the process requires it,
is a hack. If you decide to write a comment, then spend the time necessary to make sure it
is the best comment you can write.

Journal Comments

Sometimes people add a comment to the start of a module every time they edit it. These
comments accumulate as a kind of journal, or log, of every change that has ever been
made. I have seen some modules with dozens of pages of these run-on journal entries.

Position Markers

Sometimes programmers like to mark a particular position in a source file. For example, I
recently found this in a program I was looking through:

//---------------- API FETCH ------------------------

you can see any bad or good comments in linux project

https://github.com/torvalds/linux

Developing or building software is like music. A musician can play an untuned instrument well in front of people and no one can understand the quality of the music. But a professional musician can easily notice your bad performance.

Conclusion :

Generally if you work in the large team and you all have the same commenting rules and have some developers for updates your old comments can use commenting.

But you should consider that if you are in a small or medium team, committing to a project can have serious consequences.
You should consider that you have to do tasks such as bugs, updates, refactoring, adding new features, etc. and if all of these include commenting, you will completely destroy the productivity of the product system. you did and in the future that group will be doomed to failure.

Thanks for reading.

Regards Elliot :)

Top comments (0)