|
I go for a minimalist approach. Too much comments just get in the way and make the code harder to read and I really hate "captain obvious" comments:
float GetSpeed() const
void SetEditMode(int editMode)
|
|
|
|
|
The code base I am using has comments like this:
con.Open();
I remove them whenever I come across them.
There are only 10 types of people in the world, those who understand binary and those who don't.
|
|
|
|
|
Really makes you question the reasoning ability of the coder when you see statements like that.
|
|
|
|
|
You forgot to explain what "con" is in your comment
My plan is to live forever ... so far so good
|
|
|
|
|
Commenting for the sake of commenting... not that there is any value 
|
|
|
|
|
More minimalist
float GetSpeed() const
void SetEditMode(int editMode)
But I prefer the below one because the first two method names are good enough to understand the purpose. See the 3rd method
float GetSpeed() const
void SetEditMode(int editMode)
void MeaninglessMethodNameBySomeone(int editMode)
|
|
|
|
|
My personal favorite:
i++;
|
|
|
|
|
God, I hate those. That's worse than not commenting when it is needed.
|
|
|
|
|
|
My commenting (on the top) is often to give recognition that I wrote a program of sorts, as a disclaimer for everyone to see. Taught it in college, so I'm not letting that bit of knowledge go.
Otherwise, my commenting is mainly single-line statements telling "What" or "why" something is added when it isn't clear.
Obvious things shouldn't be commented, and that's the bottom line for me.
if (Broken)
then fix.this
else !fix.this
end-if
|
|
|
|
|
I do all this (and I guess I'm not alone) sometimes. Sometimes more, sometimes less. But since I (and again I guess I'm not alone) ran into the trouble of not understanding my own code when reading it later, let alone the code of colleagues, I tend to lift "sometimes" to "(nearly) always" - for nearly all most of the above cases.
|
|
|
|
|
If it's only for myself, the comments are minimum.
If it's freebies, more comments.
If it's for my work, I write comments as clear as possible.
|
|
|
|
|
More often than not have I seen code that is unclear, outdated or just wrong.
It seems people are unable to write correct and consise comments and update it when needed.
People seem to forget that a comment is just a line of code that needs to be maintained, just like the rest of your code.
Some examples of what I've seen:
int helper;
customer.Save();
int i;
int i = 42;
int j = 42;
int x = i + j; With so much noise I'd rather not see any comments at all. You'll probably still be able to figure out what code does anyway, it just might take a little longer.
Writing comments isn't fun. Most programmers I know take time to write comments, but don't take time to do it well. No one take time to update comments when they update code.
To me it's a last resort. When I write a bit of code that I really can't make any clearer than what it is I might write a comment. If a comment could make it any clearer that is.
It's an OO world.
public class SanderRossel : Lazy<Person>
{
public void DoWork()
{
throw new NotSupportedException();
}
}
|
|
|
|
|
I already said this in a poll a couple of weeks ago.
Code is like English, it's a piece of text that can be read.
The trick is to reduce the amount of code per method to the minimum and give meaningful names to all classes, methods and variables.
Comment your classes to describe the overall intention of that class. If you find multiple intentions maybe you should do some refactoring.
Comment your methods when the arguments or result require some complex logic. Still try to give meaningful names.
Reduce indentation inside methods to a maximum of 3, more than that only in specific cases, otherwise refactor your code. Small pieces of code are easier to read and more importantly, they are testable.
All these are good rules but documentation is fundamental.
Every time you push something to your source control, make sure you comment properly what you are pushing and why. Don't save any characters here. someone might see the changes history in a couple of months and it will be clear why the code changes from A to B. This is more important that why the code now is B.
Even more important, you'll be able to see not only the changes on this file but also which other filer were also changed... and why!
Also, having a proper issue project management/tracking tool is fundamental. All pushes should be linked to a task in the issue tracker.
Some source control tools support integration with issue trackers, otherwise just include the task/issue code in your push description text.
This way you can see the code, look for the history, read the author comments and if you need to have more details, read the task/issue that originated these changes.
This is all pretty fast to do. From code to the task you arrive in 20 seconds max.
Most of the time, if the code is well written, you'll have everything there, otherwise most of the times only reading the author push comments is enough.
So, again. No big in-line comments for me.
Here's a resume of what I said above:
- comment classes
- comment methods when really necessary
- use a task/issue tracking tool.
--> explain in detail what each ticket is about.
- use a source control tool
--> explain in detail what each push is about
--> keep a push per functionality, don't mix things in the same push
Cheers!
|
|
|
|
|
If you do commting, does i really help others or you do i just to follow process
SukeshMarla
www.sukesh-Marla.com
For technical trainings on MVC,WCF,Design Patterns,UML,WPF,BI,TFS contact SukeshMarla@Gmail.com or visit www.sukesh-Marla.com
|
|
|
|
|
...to comment my code so I can come back at any time in the future and pick it up again. I try.
<sig notetoself="think of a better signature">
<first>Jim</first> <last>Meadors</last>
</sig>
|
|
|
|
|
This goes for me. I try to do all - except for not commenting. Sometimes life gets in the way. And quite often I regret not doing better comments a few weeks/months/years down the line.
|
|
|
|
|
I comment any code where the purpose (the "why") may be obscure.
I think each code reader should know about the requirement of the development, in short, he/she should aware of 'WHAT'(is the requirement) , but we should comment for 'WHY'(we code this), cause reader should know 'WHY' I code this line.
(But I doubt how many times, we read comment before going through code )
Rating always..... WELCOME
The only reason people get lost in thought is because it's unfamiliar territory.
|
|
|
|
|
Code is what computers understand and comment is what human can understand. Requirement and coding are some thing different. We can not identify code on the basis of requirement. Comment is meant to quickly explain your code [And to reduce 15mins into 15secs.. ]
"When you don't know what you're doing it's best to do it quickly"- SoMad
|
|
|
|
|
The problem I have with commenting the "what" is that when making changes, you should also update the comments. If that fails to happen for whatever reason, the "what" comment is no longer explains the actual code. You're only going to find out when reviewing both the code and comment.
|
|
|
|
|
Rohan Leuva wrote: Code is what computers understand and comment is what human can understand
*Machine* code is what computers understand. High level programming languages are designed for people.
|
|
|
|