|
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.
|
|
|
|
|
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! 
|
|
|
|
|
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.
|
|
|
|
|
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.
|
|
|
|
|
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
|
|
|
|
|
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.
|
|
|
|
|
Change your code colour to green and your comment colour to black - simple!
|
|
|
|
|
Clearly, you should have given him a more useful comment, such as...
frm.Select
|
|
|
|
|
ANd wha about the flux compensator?
"Dark the dark side is. Very dark..." - Yoda
---
"Shut up, Yoda, and just make yourself another toast." - Obi Wan Kenobi
|
|
|
|
|
|
Have I given such a bad impression of him? 
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
|
|
|
|
|
And not to mention, in most cases comments a) states the obvious or b) lie to you, and only function as code-clutter. comments are the most misused feature of any programming language.
|
|
|
|
|
Another sample from our legacy code base...
If someVar = "2" = True Then
|
|
|
|
|
Its scary to think that someone who graduated with any sort of programming degree would write that. 
Just because the code works, it doesn't mean that it is good code.
|
|
|
|
|
Obviously, the culprit misheard the comment "Too true!" 
Peter
Software rusts. Simon Stephenson, ca 1994.
|
|
|
|
|
I'm tasked, as many of us are, with maintaining a codebase that was written by my predecessor. I'm finding some parts disgusting, and other, more like... fun?
Like the use of 'ToLower()' to make string comparison more safe...
if (someString.ToLower().StartsWith("text", StringComparison.OrdinalIgnoreCase))
-> Nice way to waste some cycles and memory for the Garbage Collector to play with!
if (someString.Substring(lastMarkend - 3, 3).ToLower() == "<Index>")
-> My little finger tells me, the functionality under this if must have been tested quite thoroughly.
NB: I've only changed the string names.
'As programmers go, I'm fairly social. Which still means I'm a borderline sociopath by normal standards.' Jeff Atwood
|
|
|
|
|
Oh oh! I've got the answer: #2 is false
|
|
|
|
|
#1, if you start counting at the first number.
|
|
|
|
|
Shouldn't #2 be:
if (someString.Substring(lastMarkend - 3, 3).ToLower() == ("<Index>").ToLower())
|
|
|
|
|
That would work better for sure
BTW, the string literal is just that, a string literal, when there are several 'consts'* defined some lines above
* without any const specifier or special naming of course!
'As programmers go, I'm fairly social. Which still means I'm a borderline sociopath by normal standards.' Jeff Atwood
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
