|
<message>
<response>
<attributes>
<tone>snarky</tone>
<intention>humor</intention>
</attributes>
<whatIWantToSay>
<OKImGonnaSayIt>Oh, really?</OKImGonnaSayIt>
</whatIWantToSay>
</saidIt>
</response>
</message>
Director of Content Development, The Code Project
|
|
|
|
|
Warning: Undeclared namespace
Error: Malformed XML on line 10 - error near '</saidIt>'
Make it work. Then do it better - Andrei Straut
|
|
|
|
|
Humor was lost when I found out you didn't put in a begin tag for
Just kidding...
|
|
|
|
|
Bad code doesn’t have to be a problem, as long as it’s not misbehaving, and nobody pokes their bloody nose in it. Unfortunately, that state of ignorant bliss rarely lasts. A bug will be discovered. A feature requested. A new platform released. Now you have to dig into that horrible mess and try to clean it up. This article offers some humble advice for that unfortunate situation. It was like that when I got here.
|
|
|
|
|
I have worked (maintained) on a number of projects that have bad code. Usually it is something like methods that are thousands of lines. Unfortunately, cleaning up multi-thousand line methods is impratical. All you can do is leave it better than what was started. One group did not like objects because they thought that it took too much time to create and dispose of objects. Also, a most code is done on Windows Forms (or worse ASP.NET), and the environment does not really help. So you get the view muddled with the ViewModel and Model unless you do a lot of design to avoid this. It basically comes down to do no harm.
|
|
|
|
|
Code organization is a huge thing, especially for developers (because they deal with code), and often times it’s a philosophical debate as to how code should be documented, if spaces should be used instead of tabs, what kind of documentation should be used and so on. Yet, what no one brings up is the dire issue of COMMENTING. We can all agree that comments are essential (and sometimes used to build half-ass documentation on big systems) but what no one really mentions is the fact that people are crappy commenters. From syntax use to descriptions. We just suck, really badly and that’s not the way a Zen Developer should be. // To do: write subhead
|
|
|
|
|
If you ever read Martin Fowler's Refactoring book, he has one of his bad smells as comments. I have to agree. I think what is more important than comments is good naming. If the names are good, then there is minimum need for comments. If there was a way to generate good documents from comments I might agree, but the only thing we have is the junk that Microsoft gave us with the first release of Visual Studio, which basically sucks. I would be more interested in something that tells us where naming is inconsistant, and even better, where we need to improve naming. One of the problems with comments is that they are not good if the developer cannot explain what he is doing. Give me good names any day.
|
|
|
|
|
There have been many arguments on whether code should be commented. Here's my experience.
Comments fall into two buckets: Object and method decorations - those that explain what a file, object or class does - and in-code explanatory comments that appear inside methods or blocks of code to add explanations, notes, or to explain the non-intuitive.
Anyone who says that there is no place for comments inside methods is, to me, misguided at best. Code is not a literary work of fiction open to various interpretations. It's a precise series of instructions, and sparing, sensible, well-placed notes on what's going on inside a method can prevent disasters.
There are many, many, many developers and proscribers of dogma that insist that decorative comments are also unnecessary. The standard argument is that names should be clear, descriptive, unambiguous, and as long as necessary.
If we all spoke the same language, had the same cultural background, same experiences, same literary ability, and all wrote code at exactly the same time, using the same, precise naming conventions, then yes, good naming will solve most ills and decorative comments are not that essential.
However, we don't work in this environment and it's extremely short sited, and costly in the long run, to think we do.
A term used in one context may mean something different in another. A trivial example is "Create" which could mean create a new object in memory, or store an existing object in a row in a database.
A term used in one culture may mean something different or, in fact, the opposite in another. To "table" something in North America means "to postpone for consideration". In the UK, Australia and the rest of the English speaking world "to table" means to begin consideration of the topic.
While it's straightforward to use names that are more descriptive it's important to understand that ambiguity is often difficult for a single developer to spot. They know what they mean, but it's only after other developers look at their code that it becomes apparent that other developers may not. Do not fall into the trap of assuming everyone understands what you mean.
One solution is to mandate that names be fully descriptive: CacheObject, UploadToCloudStorage, DiscussIssue. This helps a little, but very soon you hit the point where providing an unambiguous descriptive name stretches the limits of acceptable name lengths. Steve McConnell writes that method names should be between 9 and 15 characters. Good luck.
Still, this doesn't help. No matter how well you name something, how consistent you try to be, how dire your threats are to other devs, you'll always have situations where you just don't know, with absolute certainty, what a method does. With no comments the developer needs to go and read the method to understand what's happening. This is a monumental waste of time, and worse: it's frought with peril when code is read but the intent not understood.
Another issue is parameters. While the same arguments for tight and descriptive method names should be applied to parameters, it's almost impossible to encode in a parameter name things such as restrictions on acceptable input values or notes on special value handling. Comments on parameters allow you to understand the results of suppling null, 0 or empty values, and to understand the limits of what you can supply.
My approach is you should be very, very careful with object and method names, and strive to be descriptive and unambiguous and have as your goal a 95% clarity on naming. That is, 95% of the time a developer reads a method name, that name is clear and unambiguous. However, the list of ambiguous names - that 5% - will vary per developer. That list of ambiguous names may even vary over time for yourself. A simple, clear, well-written, and up-to-date comment will solve this ambiguity.
The "up-to-date" specifier raises the issue of drift. The purpose of a given method may drift slightly from its original intent. The comment attached to that method may then be slightly (or seriously) out of sync with the intent. So too may the method name. To use the argument that comments are useless, and at worst, dangerous because they may not represent what the method does can, and should be applied to method naming as well. When a developer updates a method is it easier for them to make a note of any provisos in the method comment, or is it easier for them to rename the method, and hence the object's API? The method name and the comment should both be kept up to date. Developers get tired and cut corners though.
The way I approach software development is to assume the worst. I assume the inputs to my methods will be bogus. I assume methods will return null. I assume the database will explode in a searing ball of plasma when I run a query. I also assume that my wetware will also have issues and that, at one time or another there will be confusion.
The means that all methods and parameters are commented. This ads approximately a minute of development time to each method. It also adds a small amount of time each time a method is changed to scan the comment and ensure it's consistent. It also means we have a ton of comments that, 95% of the time, add no value. However, since the set of methods that raise ambiguity or clarification issues is non-fixed, it's not practical to simply comment 5% of the code.
While it's tempting to say "just comment the methods that need it", this leads to a slippery slope that we've seen in practice again and again. The test of "what needs it" is carried out by the coder, who almost by definition finds their code clear and unambiguous. One by one "obvious" methods are created without comments and soon we have devs interupting their work and that of the author to discuss what's happening.
The application of under a minute of effort saves 5 minutes of conversation and the inherent costs involved in task switching productive developers.
Comments aren't things that hang around code like bad groupies. They are code, and when the code is updated, so too must the comment.
cheers,
Chris Maunder
The Code Project | Co-founder
Microsoft C++ MVP
|
|
|
|
|
Yes!!!
I comment everything (well, aside from class variables, but if I have one of those you can be pretty sure there is an accompanying property). I even will comment a Count property with the comment "The number of [ducks or whatever]." I do this so that everything is quickly scannable. Making them perfectly consistent prevents your flow from being interrupted.
Also, I have a standard commenting strategy for making comments on blocks of code inside methods. For example, I toss the comment "Variables" above the group of variables. This isn't so I know the obvious -- that there are a group of variables -- but so that I can quickly skip over that section without having to give it much thought.
Essentially, there is value in comments beyond what the individual comments say.
|
|
|
|
|
AspDotNetDev wrote: Also, I have a standard commenting strategy for making comments on blocks of code inside methods. For example, I toss the comment "Variables" above the group of variables
I'd recommend using #regions for that. You then get the ability to collapse the sections you want to skip over.
cheers,
Chris Maunder
The Code Project | Co-founder
Microsoft C++ MVP
|
|
|
|
|
Regions inside of regions? That's sick! That's like babies having babies. No thank you. Considering most methods I make have only a few variables, commenting works just fine.
Also, I don't collapse sections I want to skip over. I start by collapsing everything, then I expand the sections I'm interested in. 
|
|
|
|
|
I have to agree that there is often problems in one developer understanding what another means with a name, and this is why I appreciate input on naming. Fortunately names are easy to update in development environments, which is not the case with comments. I will not deny that there are times that comments are good. I just agree more with Martin Fowler, and that if you are commenting, maybe you should look at your code and see if something better can be done. I hate useless comments because they take space. I like to be able to see as much of the code as possible so I can more easily take in the flow of the code. It may be just me. I can looks at a maze, and be able to figure it out with my eyes. The code that really drives me crazy I find is really difficult to figure out anyway. This is usually because it is a really sophisticated algorithm for efficiency. Give me great naming and properly designed code any day over comments. I agree with Martin Fowler.
|
|
|
|
|
You know what I really wish for? Built in support within Visual Studio, with a hotkey, that allows yoy to collapse all comments. However, I want two versions: 1 mode that collapses decorative comments, and one that collapses all comments.
I love the intellisense comments provide, and don't always need to view them directly.
cheers,
Chris Maunder
The Code Project | Co-founder
Microsoft C++ MVP
|
|
|
|
|
There kind of is. If you do a "Collapse All" under "Outlining", all regions/methods/comments will be collapsed. I think there is a key combination that does that too. Sadly, I don't think it works on markup.
|
|
|
|
|
Kind of but not quite.
I have barebones code for a macro that will do it but never got around to finishing it.
cheers,
Chris Maunder
The Code Project | Co-founder
Microsoft C++ MVP
|
|
|
|
|
Remember to put it into a tip/trick when you're done. Just thought I'd remind you, since, you know, you'd totally forget to do that. 
Speaking of macros, I just finished writing my first VBA macro in Word to export to PDF and close the current document. Sped up my workflow, but now I feel dirty.
|
|
|
|
|
AspDotNetDev wrote: my first VBA macro in Word to export to PDF and close the current document. Sped
up my workflow, but now I feel dirty.
You should
Common sense is admitting there is cause and effect and that you can exert some control over what you understand.
|
|
|
|
|
I do have to aggree that comments can help, but most people create horrible comments.
|
|
|
|
|
Agreed 120%. 
/ravi
|
|
|
|
|
Sometimes I'm hanging-up:
all seems to be good and right, but code doesn't work as needed.
If I cant find error in reasonable time, I start commenting every line of code inside function - that really works for me.
Using such "very descriptive" commenting I solve 99% problems.
Possibly when writing I'm start to think ? 
|
|
|
|
|
So next time you find yourself feeling the need to exercise the right to complain – or just feel like venting – spend some time finding the right person to complain to. A lot of times you find your anger is less than you initially think it is and many a time you will find that you did something wrong in the first place. This way to the suggestion box.
|
|
|
|
|
While developers are incredibly intelligent, they can sometimes be a bit insecure about how smart they are compared to their peers. I've seen developer message boards tear apart billion-dollar franchises, indie darlings, and everything in between by overanalyzing and nitpicking. We always want to prove that we thought of an idea before anyone else, or we will cite a case in which an idea has been attempted, succeeded, failed, or been played out. In short, this article identifies communication techniques that are often used in discussions, arguments, and debates among game developers in order to "win" said conversations. The new Socratic method: shoot first, ask questions later.
|
|
|
|
|
These are 8 issues I hoped wouldn’t have made their way into the final build. Having said that, within a few hours of installing, I completely switched to W8 on my Air as my primary OS. It’s beautiful, quick and Windows. It's like two, two... two operating systems in one.
|
|
|
|
|
People have always culled personal libraries, of course, but the process is different in the age of the e-book. The literary classics that fill an entire book case are now all available electronically, most of them for free. Why carry “A Hazard of New Fortunes” or “The Brothers Karamazov” around when they can always be recalled from the Cloud, loaded onto a Kindle or the virtual shelf of the iBookstore? There is no friend as loyal as a book.
|
|
|
|
|
Fifty years ago this month, one of the most influential books of the 20th century was published by the University of Chicago Press. Many if not most lay people have probably never heard of its author, Thomas Kuhn, or of his book, The Structure of Scientific Revolutions, but their thinking has almost certainly been influenced by his ideas. The litmus test is whether you've ever heard or used the term "paradigm shift", which is probably the most used – and abused – term in contemporary discussions of organisational change and intellectual progress. He introduced a paradigm shift in paradigm shifts.
|
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
