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.
The Intel Ultimate Code: Ultrabook challenge[^] is an interesting experiment. On the surface it’s a coding challenge: Six developers compete for six weeks to create apps that take full advantage of the performance advances, graphic excellence, touch and sensor technologies of the latest Ultrabook computers. Scratch a little deeper and you realise that this is a 1 part coding and 5 parts hair-tearing game of strategy combined with your worst mid-term practical, ever.
Six Developers (well, eight actually - you can see the rules are already being tested at this early stage) get 6 weeks to develop the ultimate app for the Ultrabook that makes use of Windows 8, touchscreen capabilities, sensors such as gyroscope, GPS and NFC (to name a few), and the raw power of a 3rd gen Ivy Bridge i7 CPU.
For the next 6 weeks I'll be posting updates on the progress of the challengers. These are seasoned developers. They have been around the block and have a full shed of tools and tricks at their disposal. They are not to be trifled with. I am expecting, and maybe hoping, the veneer of gentile competitiveness to fall away quickly and settle down to a nice exciting game of psych.
Lee[^], for example already has an app-in-a-box application that will enable him to write his apps in Basic and target 7 different platforms. He’s using Basic. To write the ultimate app on the ultimate notebook in front of millions of developers. You can see the sorts of mind games that have already started.
George and Suresh[^] have reportedly tried out over 30 designs concepts and more than 200 assets to arrive at their final design. In less than 3 days. They also already have mockups of their final app and will be building on an existing app. In this day and age merely changing the font is enough to warrant a major release, so I’m going to be watching these guys closely. And it should be noted that any use of Comic Sans in an application leads to immediate disqualification.
Shailesh[^] from clemsoftware will be creating an Ultrabook tuned version of their BioIQ picture puzzle game. Basically: label the parts of the organisms and you win. I’m guessing touch will be a large part of the ultrabookification of this app, but what I’d really like to see is something far more immersive such as a modern day version of the children's “Doctor” game. Either through touch, or by tilting and moving the entire ultrabook you control a surgeon's knife and perform something simple like a coronary bypass. I breezed over the specs of the ultrabooks sent to the devs, but I’m sure there’s something that would add a little je ne sais quoi to it all. An electrified touchpad or the NFC chip wiping your credit cards in a “simulated” malpractice suit would add a little spice, no?
John[^] and Gavin from Soma games (I think this makes it 8+ devs, right?) are creating an app called wind up football that takes advantage of the touchscreen and accelerometer. I will be satisfied with nothing less than an app that requires you to actually kick the Ultrabook in the same way virtual golf courses have you hit a golf ball into a sheet. The touch screen can measure the location and, potentially, vector of your foot, the accelerometer can then calculate the projected path, and the gyroscope would be used to measure rotation. Their challenge will be accurately simulating the aerodynamics of a flying, spinning Ultrabook, but I assume that’s why they also mentioned the new CPUs as being integral to their app. Nice one, boys. I’m definitely looking forward to this one.
Sagar[^] and his crew made much mention of the trials of actually getting their hands on their Ultrabook, which is actually a step further than us judges have managed to get because we’re evidently embargoed from getting our greasy, cynical paws on the shiny new ‘books until the challengers have completed their penultimate post. Sagar did mention in passing that the judges pics were way cooler than the challenger’s pics so he gets 2 points this week. However, I do need to subtract 2 points for dropping the “e” in his product’s name. Ever since auto-correct was invented spelling has gone to hell in a hand-bascet.
The short version is we have a new article submission wizard (and updated systems) that provides
- An all new, single page article editor.
- An auto-save facility in case of crashes
- The ability for members to edit "edited" articles safely. No more needing to send in updates manually.
- Simplified references to uploaded files.
- A new "Alternative article" option that allows you to create alternate versions of existing articles
- An update for Tips n' Tricks so that they now use the standard article UI
- You can now upload images and downloads for blog and tip articles.
- The ability to easily switch article types (Make an article a tip, promote a technical blog to full article, etc)
The longer version:
About 6 months ago we finally had the time to revamp the aging submission wizard. I wanted a single page editor that allowed in-page (ie Ajax) file and that looked very much like what the final article would look like. The idea is that it would feel like you were editing the article in-place. Click on the title to edit it, upload a file and add the file to the content with a single click etc. And, of course, auto-save with a simple recovery model for those bad times.
I also wanted to address the need to allow our authors more access to their articles. Currently what we do is we pick the top articles and edit them. This editing corrects formatting, spelling, cleans the downloads and generally ensures that the article conforms to our standards. However, once an article is edited by an editor it is inviolate: it can no longer be updated online by the original author.
The reason for this is that, after spending so much time fixing articles, we were getting a little frustrated when members would go an re-edit the article's we edited and re-introduce all the errors we had fixed. This is understandable because they would often simply take the copy of article they had originally written, make corrections to it, then copy and paste it over whatever we had done. So we put an ednd to that for our own sanity and made a pact with ourselves (and with you) that we would be as fast as possible in posting updates you sent in.
However, this punishes those who are good authors for the sake of protecting the few that are bad, so we've come up with a compromise, and also a solution to a subtle problem.
Previously when you posted an article using the wizard, the article would be placed in a Pending queue and would be reviewed by other members who would then approve, disapprove, and/or comment on the article. After approval the article became public and everyone was happy. Except that the author could now edit their new article, upload a bunch of inappropriate material, and have it available immediately. The solution was to modify our system so that all edits of articles create a new pending version of the article. After editing, the old version will still be seen by most members, but moderators will be able to see (and approve) the new version. Once approved the new version replaces the old version and goes live.
In doing this we had to tackle a few issues with files. We choose not to store files as database BLOBs, but as system files, so where do we store your upload files while you're editing? When you start the submission wizard you haven't chosen a section, yet you can upload files. When editing an existing article you may need to upload new versions of files (updated zips or images) but we need to ensure the old version of those files and images are still available for the current article.
We ended up introducing a "Working" directory for your new uploads in order to separate out the old and the new, but this then made life difficult for those looking to reference files in their article's HTML. Previously we had the concept of a "Basename" for an article, which was effectively the name of the article's directory, and which author's used to reference an uploaded file (eg src="basename/myfile.zip"). We've abandoned that since it causes problems with name uniqueness, and in fact abandoned the whole concept of asking members to worry about directories. Now you simply reference an uploaded file by its filename, and we make sure we track things like which file (old or new) you're talking about, as well as ensuring we adjust the references in your articles during the various stages (composing to pending to available).
We've also introduced the concept of Alterative Articles. There are many, many articles that are no longer being maintained and this is a first step to allow other members to take over abandoned articles, or to simply provide different implementations such as a different language.
To provide a symmetric article experience we've now upgraded the Tips n Tricks articles to be displayed in the same manner as traditional articles (as well as their alternatives), and now make it very simple to convert a tip to a standard article, or to any other article type. No more complaint about short articles or long tips. We can quickly recategorise as needed.
This also brings a nice benefit: you can now upload images and zips to your blog and tips articles.
With regards to moving tips to the new UI - you might notice something a little weird with your rep. We moved all the comments that were associated with tips into their own separate forum for each tip instead of having the confusing comments-per-tip-plus-bonus-forum-at-the-bottom.
This release should be conidered a Beta release, so please send in all feedback and bug reports to the Bugs and Suggestions forum.
As far as we know the kinks are gone, but we have seen a couple of issues from bugs in our old system that only manifested once we moved to the new system. It's amazing how these bugs hibernate - like cicadas.
What is the URL of the article? I'll take a look and sort out whatever the issue is.
I fixed up the links and it's all good now, though I think I may have inadvertently published a version of your article you were still working on. If you wish to rollback, go to the Revisions tab on your article, choose the version you wish to revert back to, and hit revert.
I noticed while editing your article that there were line breaks in the text which I corrected. These line breaks were actual HTML line breaks (<br/>), so for instance you had the line
For this reason <br/>
it is always better to just do pre increments
which is rendered as:
For this reason
it is always better to just do pre increments
When you say "the preview" do you mean within the WYSIWYG editor, or when you hit the "Preview" button? If the former, then it could be that this line break matched the width of the editor screen so wasn't evident. If the latter then we have a bug!
With "preview" I mean the preview-button. At that time I thought it was very evident. Preview after preview-button was different from the view when the article was pending. ... but hey I did it at 2-ish at night so my mind was mush.
I.e. I think it's a bug, but I wouldn't stake my life on it.
I've tested both on live and on development and can't replicate the issue. It may have been an earlier bug we've since fixed. A few days ago I did reset the document format on a few articles that had been incorrectly set, and we also updated our rendering code.
In any case, if you see it again just let us know.
BTW - you have a ton of outstanding Draft versions of that article you recently published. Would you like me to clean up the debris for you?
* Provide the tool bar the the bottom of Editor. Mostly, when writing new article, the author would generally be writing at the end of editor. So, when author needs to apply some formatting he/she would need to make toolbar visible and then hit appropriate button. But then, the original text would not be visible. I have 22" monitor, and I write on about 150% of zoom in IE9. But toolbar isn't visible.
* Add more shortcuts, Ctrl+D is good, but what about "Formatted" for code? How to switch between HTML and WYSIWYG?
* Most authors don't know additional formatting, like "div=callout", and instead use "Formatted" instead. The parser would read it as text rather than special comment.
* On code pasting, convert tabs to 3-4 tabs, instead of author doing that manually. Also additional lines would come up when pasting.
The HTML of the original (to be edited) article may retain the old style file references (eg src = "MyArticle\MyArticle_Image.png"). In this case, it is necessary, but not obvious that the reference MUST be revised to src = MyArticle_Image.png. You provide a good clue by saying that uploaded files are relative to the article (or something like that). It would be better if that statement was augmented by something like "Check that the HTML references do not contain Directory names" -- hmmm I'm sure you can improve on that!
I do not know that the invalid refs are cleaned up on submission - I never had the guts to try. I do know that the invalid refs are NOT cleaned up on Preview.
I was updating 2 articles and only one showed that problem.
Thanks for the feedback, Jim. We tried to be clear on the submission wizard itself where an example of referencing files is shown within the list of uploaded files, as well as providing "insert" buttons that will do all the work for you.
The trick here is that, underneath it all, we still actually use "MyArticle\file.ext" (though this is now "1234\file.ext" since we've ditched basenames due to uniqueness headaches and just moved to using the article ID). Within the submission wizard editor we strip the "MyArticle\" from the raw HTML, then when you switch to design mode, add it back so the WYSIWYG mode shows the images.
So: it's the same as it always was, but when editing the raw HTML we do some magic so it seems like references are now relative to the directory containing the article.
Further, if you upload a file and reference the file using Directory\file.ext, then it should all still work. If it doesn't, please let me know which article and I'll dig in.
Thanks for the quick reply! I think I will have to look harder for the "Insert" buttons!
The one thing that threw me off is that for some reason when I switched to Html view, the MyArticle\ was not switched off. I was explicitly looking for something like that since my image was not showing in Preview. In the Design view, the older Image was the one displayed. I had deleted that Image file and add/upload a new Image with the same name. The way I fixed both of these problems was to manually strip off the "MyArticle\" from the src = and also from the download files, in Html view of course.
I was making a mod to an old article that I had updated the day before (a mod to a mod). What really irritated me was that I had had the same problem with the first update and didn't note or remember how I had fixed it then - after all, it was only 12 hours between updates - I should have remembered.
Just to make it more confusing, I was doing two articles over the same time period and the first article, of about the same vintage or even older, did not have any of these problems.
Bottom line: The suggestion I made was to address a problem that should not occur.
Should you wish to chase this one, the article's ID is 11654.
I had a quick play and it seems the article is all good now. Having the old MyArticle\ appear is annoying. This most likely happened because of some bad data our end.
Some more background: initially all articles simply referred to downloads in their MyArticle directory without any recording in our database of what was actually in that directory. We fixed this by scanning the directories and recording, and associated, downloads for files.
In some cases we had servers that were out of sync and so this association was inaccurate. When this happens the submission wizard doesn't know how to trim links because it doesn't trust anything other than what the database says.
That error will be triggered anytime a major portion of the template exists in the content.
With the new submission wizard you don't need to publish it to save it. You can hit the Save Draft button and your current work will be saved as a draft. To view drafts, just go to the submission page[^] and you'll see, on the right hand side, your drafts.