The Lounge is rated Safe For Work. If you're about to post something inappropriate for a shared office environment, then don't post it. No ads, no abuse, and no programming questions. Trolling, (political, climate, religious or whatever) will result in your account being removed.
The Agile Manifesto does not say "Thou shalt do no commenting". If you write code using descriptive naming and short methods, there should be less need to comment but there will always be situations where a comment may be appropriate.
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.
(That's an 'M')
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.
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.
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.
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.
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.
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.
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.
"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 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.
int ____preallocateSomeComments = 0;
int ___checkIfApplicationRunsOnAPlatformSupportingRegistry = 0;
int ___queryUserSettingsFirst = 0;
int ___fallBackToMachineSettings= 0;
CString location; int ___remainsEmptyIfNoDefaultLocationCanBeSuggested;
if (___checkIfApplicationRunsOnAPlatformSupportingRegistry, app.Settings.RegSupported)
location = RegGet((___fallBackToMachineSettings, app.Settings.RegUsrRoot), regidDefaultLocation);
 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
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.
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 ugly.
4) Reusable libraries need documentation. You don't want people having to scan through source code to find out how to use a type/member. The type/member should have a summary comment that explains what it does and perhaps some useful info on how to use it. No amount of refactoring is going to help you here either. Quick, given AESCrypto and SHA1Crypto which should you use to encrypt a user's password? If you have to go look at the code to figure out what each does or, worse yet, Google to determine the difference between the two algorithms you've just spent more time then you should have. The comments should provided you enough info to help you determine which to use. After all, agile is all about efficiency.
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."
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...
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.