Commenting code...
-
Last week I wrote a small library that would either startup a Form or focus an already open one, based on the Form you wanted to start. My boss wanted me to make a prototype that he could approve (approval can be reached by not using to much interfaces... He doesn't like them because it will make code harder to read and debug). So I was done writing it and showed him what I had made. First thing he said was that I didn't have comments in my code (well duh, he told me to finish it asap and he wanted to approve it first). So I had to put a comment above the Function FormCanBeShown that returns a Boolean. Yeah, what possibly could it do? Even better, I had the code
frm.Select
Boss: "What does this do?" Me: "It selects the Form... Basic Microsoft functionality..." *Hoovers over it to get MS IntelliSense prove of what I just said* Boss: "Well, I wouldn't know that, put some commentary there." And then the code looked like this:
' Activates the Control.
frm.SelectReally, was that necessary[^]?
It's an OO world.
I am always happy to err on the side of over commenting code than to leave something undocumented. I have had to work on enough code that has been poorly documented to appreciate that stuff that may be ovious to me (as the author) can be opaque to another programmer who may have a different backgroud or skill set to me. You can go overboard with comments, but semantically (despite that this is standard MS behaviour), frm.Select does not suggest activation, it suggests selection. If you boss is from a different (programming) language background, the Select keyword could do something completely different.
-
Considering that your boss asked you to write something up (who should have some knowledge of coding) and you gave him a one liner to get what he wanted working and couldn't understand that really does raise questions about his compentency. But there are two things you can learn from this. First you said that it's the default microsoft functionality (for the dot net framework I'm assuming you are saying here) which is really good but what if the person hasn't programmed using the dot net framework or didn't even know that function existed. I self teach myself a lot of stuff but unless you get training covering every functionality of each object model you can't know everything that's 'default' unless you have heard of it. You can't know that your boss knows about it and even if he did how does he know your extending the functionality or writing something totally seperate. Secondly not all people are good at reading things and having a code comment explaining the end result of the function call is a good idea especially with a single word like select is used to execute an action (i.e. select an open form, closed form, some magical form, some specific class form). My boss recently asked me to extend functionality on an existing system and then said that I had to use a specific table despite the fact I started designin it using a new table. Over the weekend I went through the system to see the impact of using that table instead of creating another one specifically designed for the purpose. I then sent an email with a list of what was needed to do to get either option working (i.e. change this, do that, etc). When I went into the office he said to see him because he didn't understand the email and after spending a bit of time talking and drawing on a whiteboard he got the idea and went yeah I can see your point and create a new table for it for now. Had I given him a few screen shots and some pictures with a few explinations it he would have been able to understand what I was saying easier. P.S. Also intellisense isn't everywhere. If you, oh I don't know, say paste the code on the web where is my intellisense :-D? I suppose it's a good think we install spell checking on our whiteboards to make sure we find typos when people write things down :laugh:.
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.
-
I am always happy to err on the side of over commenting code than to leave something undocumented. I have had to work on enough code that has been poorly documented to appreciate that stuff that may be ovious to me (as the author) can be opaque to another programmer who may have a different backgroud or skill set to me. You can go overboard with comments, but semantically (despite that this is standard MS behaviour), frm.Select does not suggest activation, it suggests selection. If you boss is from a different (programming) language background, the Select keyword could do something completely different.
RCoate wrote:
I am always happy to err on the side of over commenting code than to leave something undocumented.
Documentation should not be done in the code. I prefer seperate technical documents. Everyone can hoover over Select (in our environment) to see what it does. Now it just adds clutter which I have learned to ignore because to often it does not add anything (see my post above).
It's an OO world.
-
Last week I wrote a small library that would either startup a Form or focus an already open one, based on the Form you wanted to start. My boss wanted me to make a prototype that he could approve (approval can be reached by not using to much interfaces... He doesn't like them because it will make code harder to read and debug). So I was done writing it and showed him what I had made. First thing he said was that I didn't have comments in my code (well duh, he told me to finish it asap and he wanted to approve it first). So I had to put a comment above the Function FormCanBeShown that returns a Boolean. Yeah, what possibly could it do? Even better, I had the code
frm.Select
Boss: "What does this do?" Me: "It selects the Form... Basic Microsoft functionality..." *Hoovers over it to get MS IntelliSense prove of what I just said* Boss: "Well, I wouldn't know that, put some commentary there." And then the code looked like this:
' Activates the Control.
frm.SelectReally, was that necessary[^]?
It's an OO world.
An uncommented method is punishable by death [or at least withdrawal of fluffy cushion privileges], but commenting obvious code like that is worse than not commenting.
Panic, Chaos, Destruction. My work here is done. Drink. Get drunk. Fall over - P O'H OK, I will win to day or my name isn't Ethel Crudacre! - DD Ethel Crudacre I cannot live by bread alone. Bacon and ketchup are needed as well. - Trollslayer Have a bit more patience with newbies. Of course some of them act dumb - they're often *students*, for heaven's sake - Terry Pratchett
-
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.
Overcommented is much worse.
- Comments can go out of date, and lie to you. Alternatively, code with comments in can be copy-pasted and the comment not changed, though copy-pasting code is usually a horror all of its own anyway.
- Having too many comments will hide the few that are useful so you don't read them either.
- Comments push code off the screen (unless they are end-of-line comments, which short ones like this should be). This is true even of good comments, although in that case the trade-off is worth it, but it's always a negative so no comment is better than a bad comment.
-
Last week I wrote a small library that would either startup a Form or focus an already open one, based on the Form you wanted to start. My boss wanted me to make a prototype that he could approve (approval can be reached by not using to much interfaces... He doesn't like them because it will make code harder to read and debug). So I was done writing it and showed him what I had made. First thing he said was that I didn't have comments in my code (well duh, he told me to finish it asap and he wanted to approve it first). So I had to put a comment above the Function FormCanBeShown that returns a Boolean. Yeah, what possibly could it do? Even better, I had the code
frm.Select
Boss: "What does this do?" Me: "It selects the Form... Basic Microsoft functionality..." *Hoovers over it to get MS IntelliSense prove of what I just said* Boss: "Well, I wouldn't know that, put some commentary there." And then the code looked like this:
' Activates the Control.
frm.SelectReally, was that necessary[^]?
It's an OO world.
Looks like the biggest crime is that your boss didn't insist you comment why you were selecting the form rather than what the function did. I'm assuming there's a good reason you didn't use frm.Activate and your comment would be an opportunity to explain that to future readers. It can also be a useful technique to put down some comments first as an outline before writing the code. It doesn't take much more time and can even save time by allowing you to concentrate on the outline of a function before getting involved with the code.
-
RCoate wrote:
I am always happy to err on the side of over commenting code than to leave something undocumented.
Documentation should not be done in the code. I prefer seperate technical documents. Everyone can hoover over Select (in our environment) to see what it does. Now it just adds clutter which I have learned to ignore because to often it does not add anything (see my post above).
It's an OO world.
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.
-
Last week I wrote a small library that would either startup a Form or focus an already open one, based on the Form you wanted to start. My boss wanted me to make a prototype that he could approve (approval can be reached by not using to much interfaces... He doesn't like them because it will make code harder to read and debug). So I was done writing it and showed him what I had made. First thing he said was that I didn't have comments in my code (well duh, he told me to finish it asap and he wanted to approve it first). So I had to put a comment above the Function FormCanBeShown that returns a Boolean. Yeah, what possibly could it do? Even better, I had the code
frm.Select
Boss: "What does this do?" Me: "It selects the Form... Basic Microsoft functionality..." *Hoovers over it to get MS IntelliSense prove of what I just said* Boss: "Well, I wouldn't know that, put some commentary there." And then the code looked like this:
' Activates the Control.
frm.SelectReally, was that necessary[^]?
It's an OO world.
Clearly, you should have given him a more useful comment, such as...
' Reroutes the neutrino flow through the primary EPS conduits.
frm.SelectProud to have finally moved to the A-Ark. Which one are you in?
Author of the Guardians Saga (Sci-Fi/Fantasy novels) -
I am always happy to err on the side of over commenting code than to leave something undocumented. I have had to work on enough code that has been poorly documented to appreciate that stuff that may be ovious to me (as the author) can be opaque to another programmer who may have a different backgroud or skill set to me. You can go overboard with comments, but semantically (despite that this is standard MS behaviour), frm.Select does not suggest activation, it suggests selection. If you boss is from a different (programming) language background, the Select keyword could do something completely different.
RCoate wrote:
If you boss is from a different (programming) language background, the Select keyword could do something completely different.
I think the thing about comments here is that the Select statement is a standard .NET language construct. Therefore, you should know it if you program .NET. If you don't, you should look it up and then know it. Comments should be used for the non-obvious stuff, such as explaining (in short) an algorithm, or a couple of steps of code, or an (at first sight) unusual construct. At least, that's what I think. I'm a great proponent of commenting code though.
-
Last week I wrote a small library that would either startup a Form or focus an already open one, based on the Form you wanted to start. My boss wanted me to make a prototype that he could approve (approval can be reached by not using to much interfaces... He doesn't like them because it will make code harder to read and debug). So I was done writing it and showed him what I had made. First thing he said was that I didn't have comments in my code (well duh, he told me to finish it asap and he wanted to approve it first). So I had to put a comment above the Function FormCanBeShown that returns a Boolean. Yeah, what possibly could it do? Even better, I had the code
frm.Select
Boss: "What does this do?" Me: "It selects the Form... Basic Microsoft functionality..." *Hoovers over it to get MS IntelliSense prove of what I just said* Boss: "Well, I wouldn't know that, put some commentary there." And then the code looked like this:
' Activates the Control.
frm.SelectReally, was that necessary[^]?
It's an OO world.
Naerling wrote:
Really, was that necessary[^]?
I'm surprised your boss can read....
Sort of a cross between Lawrence of Arabia and Dilbert.[^]
-Or-
A Dead ringer for Kate Winslett[^] -
Looks like the biggest crime is that your boss didn't insist you comment why you were selecting the form rather than what the function did. I'm assuming there's a good reason you didn't use frm.Activate and your comment would be an opportunity to explain that to future readers. It can also be a useful technique to put down some comments first as an outline before writing the code. It doesn't take much more time and can even save time by allowing you to concentrate on the outline of a function before getting involved with the code.
Nah, he just "wants to see green", I quote.
It's an OO world.
-
Naerling wrote:
Really, was that necessary[^]?
I'm surprised your boss can read....
Sort of a cross between Lawrence of Arabia and Dilbert.[^]
-Or-
A Dead ringer for Kate Winslett[^]Have I given such a bad impression of him? :laugh:
It's an OO world.
-
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:
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.This calls for JavaDoc!
Excuse me for my improper grammar and typos. It's because English is my primary language, not my first language. My first languages are C# and Java. VB, ASP, JS, PHP and SQL are my second language. Indonesian came as my third language. My fourth language? I'm still creating it, I'll let you know when it's done! :-D
-
RCoate wrote:
If you boss is from a different (programming) language background, the Select keyword could do something completely different.
I think the thing about comments here is that the Select statement is a standard .NET language construct. Therefore, you should know it if you program .NET. If you don't, you should look it up and then know it. Comments should be used for the non-obvious stuff, such as explaining (in short) an algorithm, or a couple of steps of code, or an (at first sight) unusual construct. At least, that's what I think. I'm a great proponent of commenting code though.
MicroVirus wrote:
I think the thing about comments here is that the Select statement is a standard .NET language construct. Therefore, you should know it if you program .NET. If you don't, you should look it up and then know it.
I agree with that if you are doing the programming, but if your task is to scan through the code to ensure coverage/compliance with specifications, do you have to have specific language knowledge, or do you just need to understand programming constructs and patterns? I haven't had this specific issue, but I have done debugging sessions with programmers who have no background in .Net. Semantic comments can be very helpful. Not trying to suggest that things should be overcommented. I am a big believer in inteligent method and property naming so that code is largly self commenting, but I do understand what could drive that sort of comment request.
-
Clearly, you should have given him a more useful comment, such as...
' Reroutes the neutrino flow through the primary EPS conduits.
frm.SelectProud to have finally moved to the A-Ark. Which one are you in?
Author of the Guardians Saga (Sci-Fi/Fantasy novels) -
Nah, he just "wants to see green", I quote.
It's an OO world.
-
Last week I wrote a small library that would either startup a Form or focus an already open one, based on the Form you wanted to start. My boss wanted me to make a prototype that he could approve (approval can be reached by not using to much interfaces... He doesn't like them because it will make code harder to read and debug). So I was done writing it and showed him what I had made. First thing he said was that I didn't have comments in my code (well duh, he told me to finish it asap and he wanted to approve it first). So I had to put a comment above the Function FormCanBeShown that returns a Boolean. Yeah, what possibly could it do? Even better, I had the code
frm.Select
Boss: "What does this do?" Me: "It selects the Form... Basic Microsoft functionality..." *Hoovers over it to get MS IntelliSense prove of what I just said* Boss: "Well, I wouldn't know that, put some commentary there." And then the code looked like this:
' Activates the Control.
frm.SelectReally, was that necessary[^]?
It's an OO world.
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
-
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>{}
