A good start

Two recent articles (MITnews), (blogs.msdn.com), both entitled "Teaching real-world programming", report how MIT computer science students improve their code-writing skills through novel code reviews. Specifically, MIT professors Saman Amarasinghe and Charles Leiserson require students taking 6.172 — Performance Engineering of Software Systems to submit their project code for face-to-face reviews by experienced Boston area software developers.

Some comments:

(1) Having taught software engineering for some time, it is clear that a lack of basic code-writing skills hampers students' ability to succeed in computer science and software engineering. The 6.172 effort is a very good step forward.

A one-time code review certainly is helpful. To take things to a level where lifelong code-writing habits are formed may require students to carry out projects as "apprentices" to experienced software developers. In such apprenticeships, for a certain period of time, students would be responsible only for converting psuedo-code to code, allowing them to focus on developing code-writing skills without the distractions of design and algorithm development.

(2) Both the MITnews and blogs.msdn.com articles discuss the usefulness of comments. Comments in code are great if they are well-written, and certainly more helpful if they address the purpose of the code, as Barry Perlman states in a comment about the MITnews piece. It seems human nature, however, (or at least for humans who become programmers) to feel that the purpose for which code was written is obvious and does not need to be explained. Accordingly, most programmers write only about the solution represented by the code, and leave implicit some very useful information -- namely, the issue that calls for the solution.

Additionally, words by themselves are a cumbersome medium, in particular for explaining the purpose and the workings of code. Figures and videos are often necessary for effective and efficient communication. In programming languages with which I'm familiar, however, it is not possible to include figures and videos in comments.

Lastly, a comment may need to refer to two or more sections of code, raising the question, "In which section should the comment about these sections be placed?"

A commenting method termed "Issue/Solution/Link" (ISL) addresses these shortcomings by allowing comments to be composed in a format such as html, and linked with code. The ISL technique contains a mandatory "issue" section, where the issue/purpose of the code, and not the solution, is explained and described. Often, the issue can be expressed with a single question, such as, "How does the system render so smoothly?"

Although an issue may address conspicuous software features such as impossibly-fast rendering, many issues are mundane, such as: "How does the system undo a delete operation?"

The solution section of an ISL comment provides an explanation of the solution chosen to resolve the issue, largely to spare programmers the time and effort to infer the intentions underlying the code. The best-written solutions unambiguously reveal the techniques employed, and allow programmers to quickly become fluent with the related code.

Both the issue and solution sections may contain figures, videos and other non-textual data that support and clarify the written comments.

Links emanating from the issue/solution sections provide a bi-direction connection with the corresponding sections of code.

The process of developing the habit of programming with ISL comments requires a bit of discipline and effort. With time and practice, the process becomes easier and more natural.

The benefit of using ISL is quite substantial. Estimates vary. However, Peter Hallam, Microsoft's tech lead for C#, estimated once that the fraction of time a programmer spends studying code is on the order of 75%. ISL vastly reduces this 75%.

(3) Barry Perlman's comment at the end of the MITnews article is right on target -- the big payoff is the thought process required to write [good comments].