No comment
-
Yes, comments are good... But do you really think you can avoid stupidity and ignorance in the business world?
Proud to have finally moved to the A-Ark. Which one are you in? Author of Guardians of Xen (Sci-Fi/Fantasy novel)
Ian Shlasko wrote:
Yes, comments are good... But do you really think you can avoid stupidity and ignorance in the business world?
Assuming so much stupidity around, then... can you avoid stupid comments? :) In this case, comments are definitely not needed...
You can't turn lead into gold, unless you've built yourself a nuclear plant.
-
Ian Shlasko wrote:
But do you really think you can avoid stupidity and ignorance in the business world?
That question is outside the scope of the original message. We're talking about development practices, not business models.
.45 ACP - because shooting twice is just silly
-----
"Why don't you tie a kerosene-soaked rag around your ankles so the ants won't climb up and eat your candy ass..." - Dale Earnhardt, 1997
-----
"The staggering layers of obscenity in your statement make it a work of art on so many levels." - J. Jystad, 2001John Simmons / outlaw programmer wrote:
That question is outside the scope of the original message. We're talking about development practices, not business models
Nevermind... If stupidity were a resource, it would be the most universal and evenly spread resource... :)
You can't turn lead into gold, unless you've built yourself a nuclear plant.
-
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.
wolfbinary wrote:
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
Absolutely, and it also depends on the language used. Writing assembly language without comments is just nonsense. On the other hand, in a language like C#, it makes a lot of sense to spend a bit of time writing self explanatory code. Refactoring can help too keeping the code understandable. Writing comments has become one of many ways to help coping with code evolution.
You can't turn lead into gold, unless you've built yourself a nuclear plant.
-
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 just so much bollocks I don't believe anyone would be willing to put the rule in writing! Code should be self-describing - sure upto a point. BUt it becoimes illegible if you start having method names that are entire descriptions of themselves
CustomerListIncludingBasicDetailsFordisplayingInAGridOrSimilarGui GetCustomerListIncludingDisabledCustomersWithExistingOrdersButExcludingCustomersWithZeroDebt();
is just somehow not readable! Sure its an exaggeration. IMHO you should START every method by writing the comments (this is akin to TDD). Comment th method, describing what its purpose is, that is ALL a developer should need to look at again UNLESS the method needs to be refactored due to errors or changes in requirements. You SHOULD be able to read a program merely by reading the comments. Why don't people code like this in the real world? Because their lazy, good for nothing, spotty pizza eating nerds, that's why! Oh, and hey also realise that comments often do not get maintained with the code, and so become out of date, and so become useless. So - let's fix the problem by not commenting, so making it go away. With agile you are surely doing code reiews? Well, these should include the comments (in fact they souldSTART with the comments - the code merely reflects the descriptiuno which is based on the specification. And also (Ohhhh you got my gander up!) I'd be interested in seeing in this rule book whatg the justifiation for that rule actually is? Or is it just "thou shalt not..." IMHO any coding rule, guideling, practice, expectation or standard MUST have a justification and MUST be fluid over time. "Do not use Comments - because I don't like them" doesn't cut it.
___________________________________________ .\\axxx (That's an 'M')
-
That's just so much bollocks I don't believe anyone would be willing to put the rule in writing! Code should be self-describing - sure upto a point. BUt it becoimes illegible if you start having method names that are entire descriptions of themselves
CustomerListIncludingBasicDetailsFordisplayingInAGridOrSimilarGui GetCustomerListIncludingDisabledCustomersWithExistingOrdersButExcludingCustomersWithZeroDebt();
is just somehow not readable! Sure its an exaggeration. IMHO you should START every method by writing the comments (this is akin to TDD). Comment th method, describing what its purpose is, that is ALL a developer should need to look at again UNLESS the method needs to be refactored due to errors or changes in requirements. You SHOULD be able to read a program merely by reading the comments. Why don't people code like this in the real world? Because their lazy, good for nothing, spotty pizza eating nerds, that's why! Oh, and hey also realise that comments often do not get maintained with the code, and so become out of date, and so become useless. So - let's fix the problem by not commenting, so making it go away. With agile you are surely doing code reiews? Well, these should include the comments (in fact they souldSTART with the comments - the code merely reflects the descriptiuno which is based on the specification. And also (Ohhhh you got my gander up!) I'd be interested in seeing in this rule book whatg the justifiation for that rule actually is? Or is it just "thou shalt not..." IMHO any coding rule, guideling, practice, expectation or standard MUST have a justification and MUST be fluid over time. "Do not use Comments - because I don't like them" doesn't cut it.
___________________________________________ .\\axxx (That's an 'M')
_Maxxx_ wrote:
You SHOULD be able to read a program merely by reading the comments.
Completely agree! In fact, if the code is complicated enough, I start out with comments to give myself a list of things to do. I start with the high level comment then I make more specific comments as I write code. If the code is pretty routine, I'll usually write a bunch of it then come back later to comment it (for the benefit of the next person who will work on it). Makes it easier to break code into logical chunks, which can be more readily understood. I don't see why others see comments as a problem.
-
I would be quite verbal in my protestations regarding the "no comments allowed" policy. Agile is fine (I guess), but stupidity and ignorance should be avoided at all costs.
.45 ACP - because shooting twice is just silly
-----
"Why don't you tie a kerosene-soaked rag around your ankles so the ants won't climb up and eat your candy ass..." - Dale Earnhardt, 1997
-----
"The staggering layers of obscenity in your statement make it a work of art on so many levels." - J. Jystad, 2001John Simmons / outlaw programmer wrote:
I would be quite verbal in my protestations regarding the "no comments allowed" policy. Agile is fine (I guess), but stupidity and ignorance should be avoided at all costs.
I was going to reply to the OP, but you said exactly what I wanted to say.
I wanna be a eunuchs developer! Pass me a bread knife!
-
I don't think they're allowed either, which is fine by me as I HATE them. First thing I always do is CTRL+M+P to expand them away, you know so I can see the code.
Regards, Rob Philpott.
I disagree. Regions are useful if used sparingly and appropriately.
do or do not, there is no try
-
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.
Meaningful method names are all very well and good but don't often help with how the method is implemented, and sometimes if you were to fully describe a method in its name it would be impossible to read! For instance I've just finished writing a method which takes a hex value as a string (because that's how its supplied) and converts it to a single precision value. Now naming the method appropriately is fine and breaking it apart is okay as well but sometimes you just really need to explain why you're doing something so that people who are unfamiliar with the code can easily understand what is going on. I agree that bad comments are as good as no comments at all but I think that code should be commented. To not do so is the same as loading a gun, aiming it square at your foot and pulling the trigger.
-
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.
I've worked with that. It's based on XP Programming, but even there, comments are not disallowed, they are discouraged. It's good as a practice (to work like this for two months): you really learn to create meaningful code etc. BUT, after these 2 months of practice, you shouldn't apply it to the letter. There are these points in the code where you do somethings strange, because of some weird interaction in the frameworks you're using. There are also these other points where you do something honestly complicated, or you use an external or legacy library with bad naming conventions. So, having a couple of comments per file can reaally help explain some choices. (and yes, #region is allowed :P)
-
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.