No comment
-
Where I work presently, we are 'agile' if you will. Very disciplined agile. One rule the team has is that comments in code are not allowed (no, really). Code should be self describing, and if you need to comment something, you're better taking it and putting in its own method with a meaningful name. I'd be interested to hear what people's opionions on this are.
Regards, Rob Philpott.
Surely you must therefore end up with places where you have a pile of nested functions where one function and a comment would have been better (less code, easier to follow and less maintainence). I've always felt you should write the best code to solve the problem (which is after all the actual goal) and comment as needed. The the best code to replace comments and documentation is probably not the best code for the problem you're addressing. Plus of course I am actually a human not a compiler. I read english faster than code.
-
Where I work presently, we are 'agile' if you will. Very disciplined agile. One rule the team has is that comments in code are not allowed (no, really). Code should be self describing, and if you need to comment something, you're better taking it and putting in its own method with a meaningful name. I'd be interested to hear what people's opionions on this are.
Regards, Rob Philpott.
I got about halfway through the responses to this before I had to reach for my duct tape to prevent my head from exploding. No comments? Really? That's the stupidest thing I've ever heard. And I used to work for IBM. They collected statistics on klocs! So I've heard some pretty stupid things.
-
Where I work presently, we are 'agile' if you will. Very disciplined agile. One rule the team has is that comments in code are not allowed (no, really). Code should be self describing, and if you need to comment something, you're better taking it and putting in its own method with a meaningful name. I'd be interested to hear what people's opionions on this are.
Regards, Rob Philpott.
I use to add jokes, odd stories and stuff as comments in my code. Much like here at the lounge. Sometimes I would add comments about coding quirks, crazy stories about why I chose one design over another. It was nice to hear new developers laughing in their cubicles while tasked with maintaining my old code rather than cussing me out.
-
Use a gun on the moron who came up with the no comment policy.
Panic, Chaos, Destruction. My work here is done.
Agreed
Know way too many languages... master of none!
-
Where I work presently, we are 'agile' if you will. Very disciplined agile. One rule the team has is that comments in code are not allowed (no, really). Code should be self describing, and if you need to comment something, you're better taking it and putting in its own method with a meaningful name. I'd be interested to hear what people's opionions on this are.
Regards, Rob Philpott.
Example of self-explanatory code: UINT ReturnIDOfTheCommandReceivedFromPressingTheDefaultButtonInSecondTabOfTheUI(UINT* PointerToArrayContainingCurrentStateOfTheControlsInTheCommandUIWindow) {... Comments? Who needs 'em? :laugh:
-
Where I work presently, we are 'agile' if you will. Very disciplined agile. One rule the team has is that comments in code are not allowed (no, really). Code should be self describing, and if you need to comment something, you're better taking it and putting in its own method with a meaningful name. I'd be interested to hear what people's opionions on this are.
Regards, Rob Philpott.
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.
-
Where I work presently, we are 'agile' if you will. Very disciplined agile. One rule the team has is that comments in code are not allowed (no, really). Code should be self describing, and if you need to comment something, you're better taking it and putting in its own method with a meaningful name. I'd be interested to hear what people's opionions on this are.
Regards, Rob Philpott.
-
Where I work presently, we are 'agile' if you will. Very disciplined agile. One rule the team has is that comments in code are not allowed (no, really). Code should be self describing, and if you need to comment something, you're better taking it and putting in its own method with a meaningful name. I'd be interested to hear what people's opionions on this are.
Regards, Rob Philpott.
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
-
Where I work presently, we are 'agile' if you will. Very disciplined agile. One rule the team has is that comments in code are not allowed (no, really). Code should be self describing, and if you need to comment something, you're better taking it and putting in its own method with a meaningful name. I'd be interested to hear what people's opionions on this are.
Regards, Rob Philpott.
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.
-
Where I work presently, we are 'agile' if you will. Very disciplined agile. One rule the team has is that comments in code are not allowed (no, really). Code should be self describing, and if you need to comment something, you're better taking it and putting in its own method with a meaningful name. I'd be interested to hear what people's opionions on this are.
Regards, Rob Philpott.
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.
-
Where I work presently, we are 'agile' if you will. Very disciplined agile. One rule the team has is that comments in code are not allowed (no, really). Code should be self describing, and if you need to comment something, you're better taking it and putting in its own method with a meaningful name. I'd be interested to hear what people's opionions on this are.
Regards, Rob Philpott.
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?"
-
I disagree. Regions are useful if used sparingly and appropriately.
do or do not, there is no try
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.
-
Sounds like the rules were made by a zealot who doesn't have to write or read code himself/herself.
Then later comes and asks you "What the hell were you thinking!" and "What does is this doing?"
-
Where I work presently, we are 'agile' if you will. Very disciplined agile. One rule the team has is that comments in code are not allowed (no, really). Code should be self describing, and if you need to comment something, you're better taking it and putting in its own method with a meaningful name. I'd be interested to hear what people's opionions on this are.
Regards, Rob Philpott.
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.
-
At a previous job a consultant mentioned and then explained what agile was and then he declared that's what we'd been doing all along. He missed the part about defining what you're doing and then not changing that until sometime later as another cycle. Agile, as I've seen it, mostly keeps documentation of the system from happening and foresight of the product or system from taking place. When customers ask for documentation we didn't have much to say other than to sputter and then commit to making some later. It was never part of the project. Poorly written comments are just as bad as no comments. What the code is doing doesn't necessarily explain the why. Just my opinion though.
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.
-
Where I work presently, we are 'agile' if you will. Very disciplined agile. One rule the team has is that comments in code are not allowed (no, really). Code should be self describing, and if you need to comment something, you're better taking it and putting in its own method with a meaningful name. I'd be interested to hear what people's opionions on this are.
Regards, Rob Philpott.
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 -
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.
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.
-
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.
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.ClickIf 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 IfEnd Sub
-
Where I work presently, we are 'agile' if you will. Very disciplined agile. One rule the team has is that comments in code are not allowed (no, really). Code should be self describing, and if you need to comment something, you're better taking it and putting in its own method with a meaningful name. I'd be interested to hear what people's opionions on this are.
Regards, Rob Philpott.
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?
-
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.ClickIf 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 IfEnd Sub
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.
