A question about documenting style

[readable_team]

Hello everyone,

My friend and I have started creating an IDE extension that will be able to comment your code for you. We were wondering if you guys prefer commenting on single lines of code within functions OR commenting a summary of what your functions do as a whole. If you use one or both could you explain your reasoning behind it?

Thanks so much guys. The help is appreciated.

 

[Johna]

I use both, but I think I prefer to use

commenting on single lines of code within functions

because I know exactly what everything does, so If something in my code isn't working, I can easily find it.

But if I code long lines of code, I'm often too lazy to add comments everywhere, so I do your second option.

commenting a summary of what your functions do as a whole

 

[Antero360]

Hello everyone,

My friend and I have started creating an IDE extension that will be able to comment your code for you. We were wondering if you guys prefer commenting on single lines of code within functions OR commenting a summary of what your functions do as a whole. If you use one or both could you explain your reasoning behind it?

Thanks so much guys. The help is appreciated.

For personal projects, I prefer summary comment blocks at the top of functions. Will only comment inside of the function if the function is complex enough. If your naming conventions for both functions and variables are readable enough (and by that I also include if you can tell what the variable will be without having to "hover over while you code"... (and yes, I am a little biased against the overuse of var in c# lol)), then you shouldn't need to much commenting. For work, I use line comments on complex code.

 

[Deleted member 2829]

Hello everyone,

My friend and I have started creating an IDE extension that will be able to comment your code for you. We were wondering if you guys prefer commenting on single lines of code within functions OR commenting a summary of what your functions do as a whole. If you use one or both could you explain your reasoning behind it?

Thanks so much guys. The help is appreciated.

Both, depending on whether a single statement or a block of code must be clarified. I do find commenting code, especially one-liners, a little overrated though. You tend to see silly stuff like this

count++; //increment counter

Not everyone will agree, but IMO with proper coding style, naming, and layout, a lot of comment is unnecessary. If code needs commenting, consider if it should (and could) have been more transparent. Nothing worse than pages where you have to dig for the statements in a mire of comments.