No comment

[Lost User]

Thinking that your code is self explanatory is like thinking that your code is bug free and doesn't require QA testing. I have the following convention in my team. During code review, if your peer doesn't understand your code, put comments. As for your boss, have him read this thread.

[Phasma]

As one maintaining a business app written over 20years in c, where there is hardly any comments, i'm against this. For Christmas i wish for comments, in the code i'm maintaining

[Chris Maunder]

The rule that proper naming should mean no comments is great if (a) Everyone in your team is as good at you in naming things (b) everyone on your team think that every word you use means exactly the same thing as you These two basic requirements for a "no comment" system may work wiht 2, or maybe 3 developers, or may work on very simple code that, say, takes data from a database and displays it, but for everything else you're screwed. I'm Australian, I work with Canadian, Ukrainian and US developers. We are constantly clarifying to each other what we mean (in a good way) but it only reinforces how differently we all treat words in the English language. On top of this, what you yourself consider a name to mean one day may very well not be the intention 6 months later.

cheers, Chris Maunder The Code Project Co-founder Microsoft C++ MVP

[k bl]

Hey I've got an idea, let's make something completely useful, and then not use it! When you can't explain it in a comment, just use long identifiers ;) : Decimal ClassThatTakesADecimalRoundsItToTheNearestSecondDecimalAndThenReturnsItAsADecimalVeryEffeciantly(Decimal num) { return Math.Round(num, 2); }

ASP.Net meets JQuery... Imagine the possibilities.

[bwestrick]

I think a no comment policy is a bit idealistic. Sure, code should be written so that it can easily be read, but many times the assumptions that one programmer makes are not the same as another reading the code. Or subtleties might be missed. At other times efficient code is not readable without comments. I think a no comment policy is a bit like saying, everyone should drive safe so we don't need seatbelt and insurance. Or, nobody should steal so we don't need to lock our doors. i just don;t think we are there yet.

[Anna Jayne Metcalfe]

That's at least as nuts as thinking that waterfall development is a good idea. :omg:

Anna :rose: Tech Blog | Visual Lint "Why would anyone prefer to wield a weapon that takes both hands at once, when they could use a lighter (and obviously superior) weapon that allows you to wield multiple ones at a time, and thus supports multi-paradigm carnage?"

[Jason Christian]

I think regions are great. Crtl+M+O to collapse everything, and then open up the section I need to work with. If I'm looking for the implementation of an interface, I don't have to scroll through all the property defintions first, etc... As for comments, I agree they should be used sparingly and more thought put into making the code self-documenting. Comments can get out of sync with the code, and if you aren't being careful in writing descriptive code why would you be careful about writing a descriptive comment? However, there are times when comments are necessary, so banning them completely is ridiculous. For instance you are calling a 3rd party API that has something uninituitive, and you want to explain why you are calling it a certain way - a method name isn't going to provided that information without being ridiculous ( i.e. DoSomethingWithExtraParametersSo3rdPartyAPIIsHappy ). Comments are also useful to explain the rationale behind a hack when the expected technique won't work for some reason.

[James Lonero]

Then later comes and asks you "What the hell were you thinking!" and "What does is this doing?"

[James Lonero]

I have heard of that mentality since the early 80s, especially from those in the UNIX world. The logic is good if all you’re concerned with is what it is doing and how it is being done. You could even put what the method does in the method name. The thinking is that each method should do one and only one thing has been a mantra for years. Coming from the world of C, many years ago, coders liked writing very tight code using many short cuts making the code hard to follow. And, thus, making it more difficult to understand. In today’s world, business dictates that we get the product out ASAP, which may necessitate the rule of “no comments”. The consequences is that at a later point, when someone else picks up your code or you restart in it, the knowledge of what it was doing is degraded and you need to spend time reviewing your work. Also, comments are useful to map code to requirements or bug fixes.

[Alan Burkhart]

I've always favored a few lines of comment before a code block to provide an explanation of it's purpose, then if necessary add a few brief comments at the end of a line of code. A year later I can go back and read it and actually remember what I was doing.

[peterchen]

Lots of possibilities for abuse I see.

int _____SuggestDefaultLocation;

int ____preallocateSomeComments = 0;
int ___checkIfApplicationRunsOnAPlatformSupportingRegistry = 0;
int ___queryUserSettingsFirst = 0;
int ___fallBackToMachineSettings= 0;

CString location; int ___remainsEmptyIfNoDefaultLocationCanBeSuggested;

if (___checkIfApplicationRunsOnAPlatformSupportingRegistry, app.Settings.RegSupported)
{
if (!(___queryUserSettingsFirst,
location=RegGet(app.Settings.RegRoot,
regidDefaultLocation, location.GetLength())))
location = RegGet((___fallBackToMachineSettings, app.Settings.RegUsrRoot), regidDefaultLocation);
}

Instant win!

---

[edit] On a serious note: Ideally, well written code can tell you clearly what it does. Comments are to tell the reader why.

Personally, I love the idea that Raymond spends his nights posting bad regexs to mailing lists under the pseudonym of Jane Smith. He'd be like a super hero, only more nerdy and less useful. [Trevel]
| FoldWithUs! | sighist | µLaunch - program launcher for server core and hyper-v server

[FrankLaPiana]

One of the comments that I remember (from an article about comments), is that experienced programmers don't always comment what a section of code does, but it was a very good practise to explain why the section was coded that way. Explaining why a particular algoritm was used was more useful than explaining how the algoritm worked.

[Alan Burkhart]

Why not? :cool:

'[example...]

'this sub converts a vertical list to a delimited list using a delimiter
'chosen from the delChr array using the SelectedIndex property from the
'combobox in the GetDelimiter dialog
Private Sub menuLines_VertToDel_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles menuLines_VertToDel.Click

If sci.Selection.Text.Length = 0 Then 'stop if no text is selected
  MsgBox("You must first select some text to convert.", MsgBoxStyle.Information, title)
  Exit Sub
End If


res = dialog\_GetDelimiter.ShowDialog

If res = Windows.Forms.DialogResult.OK Then
  Try
    Dim dc As String = delChr(dialog\_GetDelimiter.cmb\_Delimiter.SelectedIndex) 'char from array
    sci.Selection.Text = sci.Text.Replace(Environment.NewLine, dc) 'replace Newline with delimiter chr
  Catch ex As Exception
    MsgBox(ex.ToString, MsgBoxStyle.Exclamation, title)
  End Try
End If

End Sub

[kjthorn]

This only sounds workable if (1) you never need to optimize anything for speed, (2) you don't have to credit anyone else's code, (3) no algorithms were harmed in the making of your software, (4) your code is single-threaded, and (5) your software doesn't do much more than move things around and apply simple transformations. Otherwise, sure, no comments. Why not?

[FrankLaPiana]

Well I actually do tend to comment what the function does, ie, "FindCustomerName". But I think the reason was why a particular algorithm was used... which depends upon the complexity of the requirements and the implementation of the logic. // Find object by using custom mapping routine that locks nodes into memory. // This custom map does not need locking for existing items and multi-thread use. // Tested as fastest method and avoids double de-reference of pointer to get to the actual data. program logic blah blah blah // object was not found, must lock here and retry search. program logic blah blah blah // object still not found, create it and add it to the map while we're locked.

[CoolDadTx]

I'd look for a new job as your team evidently heard about Agile, thought it was great and then implemented it wrong. Agile has nothing to do with commenting code. Agile is about reducing all the lengthy, useless documentation that follows a project because it assumes the docs will be wrong. Such docs are unrelated to code comments. Comments help clarify what the code is suppose to do. I do agree that you should not comment every line of code. I also agree that you should use meaningful names and proper modularity but it is important to remember a couple of things that comments provide that you simply can't get in code: 1) Comments specify what the code is suppose to do, not what it actually does. Unless you write perfect code there is always a chance that you'll introduce a logical error into your code. When reviewing someone's code if the comments don't match the code then it should send up a red flag. Just having the code won't help you here. 2) Comments justify why code works the way it does. This is especially important when you don't use verbose documentation (since that goes against Agile). Sometimes there are business rules or decisions that are made by analysts or others and your code just has to do it. It is therefore important to identify why the code works the way it does. For example a block of code that is difficult to read and manage because it has been heavily optimized would probably send an agilist into refactor mode but wait. If a comment above the code said something like "This code is called hundreds of times a minute and has been optimized using profiling and memory utilization tools to make it as fast as possible" then the agilist would know to leave the code alone. Yes in a real world all code is perfectly designed but the more you modularize and OOD a problem the slower the app gets. 3) Agile should not dictate type and variable names. Sure you can use descriptive names but there comes a point where the name of identifiers simply gets too long. For example suppose you are writing some base class types and you need to implement a base class that implements a couple common interfaces such as IEditableObject, INotifyPropertyChanged and IDataErrorInfo. Try naming that type in a meaningful way. Chances are you're going to reduce it to something like BaseBusinessObject or something. Now how does that in any way convey information about the interfaces being implemented? It doesn't. You'd have to look at the code itself. Start nesting these types and it can get ug

[BrainiacV]

In the late 70's I was working in a shop where I was told "Comments are a waste of time." "Oh, really?" I replied. "Why yes, the instruction tells you what it is doing." "But it does not tell you why it is doing it." I was waved off. A year later I had the supreme satisfaction of watching this programmer looking through his own programs with the most quizzical look on his face. He couldn't figure out from the instructions alone what the intent or operation of this program was. Years later, when I was teaching programming to career changing adults, I said "You should be able to lay a piece of paper over the left hand side of a program, read the comments on the right and tell me what it doing." My mantra was "Code tells you what, comments tell you why."

Psychosis at 10 Film at 11

[CDMTJX]

Code I write or edit gets comments. If for no one else, *me* if I come back in a few years time not remembering what I did. I've had to maintain old code where the comments were all that had me able to figure out what the programmer had in mind. Why I shouldn't rewrite something that looks wrong but isn't. Why was something changed some number of years ago. Bad obsolete comments aren't good, but any hints about the code are generally useful, and I can update them...

[SanityMonger]

I once had an English teacher who required that we write a 5-pager without using any form of the verb "to be". We could use it as what was then called a "helper verb", as in "she was having a hard time with the assignment", but not as the main verb in the sentence. We of course grumbled about this (it was not even a writing class), but what I found was that in the end it REALLY improved my writing. I.e. like all things, the verb "to be" has its uses, but one can become too reliant on it. The "no code comments" policy seems like it could make a good exercise for improving one's coding (i.e. if you're putting in a lot of comments, then think about how to rename methods and variables or restructure the code to make it more self-documenting), but as a blanket policy it's of course ludicrous.

[Steve Smith]

I recently posted a detailed essay on comments, which you might find relevant to this discussion. You'll find it here: http://stevesmithblog.com/blog/when-to-comment-your-code/[^]

Steve Smith The Code Project Microsoft Regional Director, ASP.NET MVP