Commenting code...
-
there should be minimum comments in the code, as they are not maintained properly and often lead to confusions. comments should be put unless some very convoluted things are going on
No matter how fast light travels, it finds the darkness has always got there first, and is waiting for it
-
We have programmed with .NET WinForms for 7 years now, my boss too (and probably more than any of us). Documenting methods that are already documented just seems like such a waste of space. Our code is full of such obvious comments...
' Set the caption of the label.
Label1.Test = "Saved successfully"' Saves the Product.
customer.SaveDo you see the problem? Everyone can see that the TEXT of a label is set, even though comments say caption (all throughout the software, copy/paste mentality). Even worse for the product/customer. People copy and edit code, they don't edit comments. If I had to comment each and every .NET Framework method like that the development time gets quite a bit longer... I have learned to not read comments, because they do not currently add any value to our code, just clutter. Every comment needs to be maintained, just like any other piece of code. For some reason it never happens. And everytime my boss asks me to comment the obvious once again I die a little inside. I'm not sure what is worse, uncommented code or overcommented code. At least uncommented code says what it does (right there in the code), if comments do the same is always a question.
It's an OO world.
Terrible comments. The first "Set the caption of the label." What does the label pertain to? Better yet, change the name of the label to "lblSaveStatus" or something like that. GREAT code is mostly self-documenting. The second comment looks just plain wrong. From the code, it looks like you are saving a "Customer", but the comment says "Saves the Product." The comment is inconsistant with the code.
-
Terrible comments. The first "Set the caption of the label." What does the label pertain to? Better yet, change the name of the label to "lblSaveStatus" or something like that. GREAT code is mostly self-documenting. The second comment looks just plain wrong. From the code, it looks like you are saving a "Customer", but the comment says "Saves the Product." The comment is inconsistant with the code.
tobep wrote:
GREAT code is mostly self-documenting.
My boss just doesn't want it... Nothing beats commenting the hell out of your code :(
It's an OO world.
public class Naerling : Lazy<Person>{}
-
Naerling wrote:
I prefer seperate technical documents
The 1970's called, they want their developer back ;-) If people rarely keep comments in sync with the code, the chance of them keeping separate technical documents is almost nil. Almost every project I've worked on with large amounts of technical documentation has been government contracts - badly run, badly designed, over budget and frequently failing, but I've not seen a single example of useful technical documentation on any project I've been lucky enough to work on. At least a comment stands some chance of being updated.
Rob Grainger wrote:
The 1970's called, they want their developer back ;-)
If people rarely keep comments in sync with the code, the chance of them keeping separate technical documents is almost nil.Actually that is exactly what our company did in the 80s to get ISO certification. Our entire software development process was defined around keeping everything in sync. And it worked!
Rob Grainger wrote:
Almost every project I've worked on with large amounts of technical documentation has been government contracts - badly run, badly designed, over budget and frequently failing, but I've not seen a single example of useful technical documentation on any project I've been lucky enough to work on.
Funny you are saying this, because before we introduced extensive documentation and the process around it, we did have issues with budget and time overruns, but rarely after. I've learned - by example - that a well organized process put into action by a disciplined team can produce incredibly high quality output with predictable results. And the documentation was crucial to that! Before we had that extensive documentation, we lost too much time reimplementing stuff that wasn't specified in sufficient detail. Of course, back then the process we had was a modified waterfall model. Nowadays, with agile development, you need a lot less documentation - it's bound to change anyways. In the end, what it all comes down to is that you need a good process. if that process requires a lot of documentation, then you need that. If the process can do without, then you don't. OTOH, if the process is bad, then no amount of documentation can save you.
