Some Comments on Comments

Code is communication, and comments can make a world of difference when it comes to making code clear and readable. Every seasoned developer has seen code that could have been made clearer with a few well-placed comments. At the same time, it isn’t unusual to find code that is littered with comments that are stale, unclear, unhelpful or just downright irritating.

Nothing can be quite so helpful as a well-placed comment Robert C Martin

Knowing when to comment and how to make a comment is an art, and one that clearly separates good programmers from poor ones. It is worth taking time, then, to review our practice in comment-writing. This is particularly true for those of us who have been around for a while. Coding practices and technologies have changed, and some of our old habits are inappropriate in modern programming environments.
The rest of this article outlines my current thinking on code comments, based on my research and experience as a programmer.

The Purpose of Comments

The purpose of comments is to help to make code readable.
For this reason, comments should be:

  • Terse
  • Readable
  • Helpful
  • Correct
  • Unambiguous
  • Maintainable
  • Placed as near as possible to the code that they’re commenting on

Unhelpful Comments

Comments that should be code

As far as possible, code should be self-describing. This implies that comments should explain why, because code already explains how.

Comments do not make up for bad code Robert C. Martin

  • Comments should not repeat what the code already says, for example:

  • Where possible, refactor code to eliminate comments
    • Better function / variable names can eliminate the need for comments
    • A simpler architecture or structure requires less commentary
    • Shorter methods eliminate the need for closing brace comments, like this:

    • Split functions / classes into smaller units to eliminate comments that act as section headers or division markers

Comments that should be part of source control

…and if you aren’t using source control then you already have a bigger problem than bad comments!

  • Attributions (developer’s names)
  • Code version numbers
  • Journal comments (who did what and when)
  • Commented-out code
  • History of changes, like this:

Misleading comments

One of the biggest problems with comments is that they rot over time. The comment you write today may not match the code you write tomorrow.

  • Ambiguous or unclear statements
  • Outdated information
  • Comments that don’t apply to the present context
  • Information that applies only to specific cases
  • Comments that are just plain wrong

Comments that create unnecessary work for the author / maintainer

If comments take up too much time to maintain then they are less likely to be maintained.

  • Non-trivial formatting. Insisting, for example, that all comments are in neat boxes made of asterisks
  • Mandated comments – that your boss / process / toolset tells you should be there but which add no real value, for example:

  • Markup in comments (except when it is required by tools that generate documentation)

Comments that create unneccesary work fort the reader

  • Noisy comments
    • Comments that contain much information / irrelevant information
    • Chatty comments. Blah, blah, blah.
  • Poor spelling / punctuation in comments
  • Non-local information (such as information how callers will use a value returned from a function – that’s the caller’s business)

Unprofessional comments

  • Anything offensive, derogatory or insulting
  • Jokes / cultural references should be included sparingly, sensitively and kept short and/or clearly delimited as such

The practice of inserting jokes or cultural references in comments is a matter of some debate. Some people think they are invariably unprofessional, as they convey a lack of seriousness and waste time for both their authors and readers. Others (myself included) feel that they are conducive to a good working atmosphere. However, they should be easy to skip over for readers of the code, and should never risk your professional reputation nor that of your employer/customer.

Beneficial Comments

File headers

  • Copyright and other legal notices (everything else can be omitted)

Explanations and clarification

  • When you can’t explain something in code (by using a function name, for example)
  • Explanation of the intent of code
  • Clarifying the reason for a decison
  • Clarification of code you can’t alter, like library call results

To draw attention

  • Warnings of consequences
  • Drawing attention to important things that appear inconsequential

Comments parsed by development tools

  • TODOs
  • Documentation markup

Comments that save the reader time

Some of this last set may be a little controversial, but I find them beneficial:

  • Brief explanations of concepts, algorithms etc. so save the reader referring to external documentation
  • Comments that help interpret the solution in terms of the problem domain
  • Comments that signpost external documentation (such as urls)

Further Reading

  • “Clean Code” by Robert C. Martin

Best Practices: Why aren't they followed?

We all know it is a good idea to follow best practices, but we also know that we don’t always follow it. I find that interesting.
Now, when I want to change something, I find it helpful to understand why things are the way they are. It is worth asking, then, why don’t we follow best practice? And what can I do about it?

Ignorance

Simply not knowing what constitutes best practice appears to be a reasonable excuse for not following best practice. For someone new to the discipline, this is fair. But what about those of us who have been in the profession for some time? Is it enough to argue that nobody has shown us the way? That nobody has made the information we need available to us? Well, I do sympathize with people who face these issues. But only to some extent.
The truth is, my career is my responsibility. I have a professional responsibility to develop our skills in our chosen craft, and we live in an age where this information is more readily available than it might have been in the past. I can choose to learn if I want to.

Pressure to Deliver

My client needs a solution delivered yesterday, and my family needs me at home in the evening. When am I supposed to learn, let alone implement, best practices?
Actually, the problem for the company is not lack of time. It is lack of understanding. The reason I say this is that best practices, by definition, deliver more value for less cost. If they didn’t, they wouldn’t be best practices. The way to deal with this, issue, then, is to find ways to communicate the benefits of best practice to the people around us – having firmly established what best practice actually is as it applies to our situation. We need to persuade managers that a small investment now – a delayed delivery – will reap long-term benefits.

Take time to go fast.

Part of the solution is to recognize  that developing my skills isn’t my responsibility alone. My employer has a responsibility to support my personal development – to give me time and resource to grow so that I can add more value to the company. Sometimes, however, organizational leaders need to be reminded of this. I may have to persuade my managers that allowing me resource to grow will benefit them in the long term.

Other Developers

I am led to believe that, sometimes, other professionals actually foster ignorance of best practice. They may feel threatened by having to learn new skills or by their own practice being challenged. They may feel that they already know best, that their methods are tried and tested. They may have worked hard to develop their own practice, and as a result have formed a strong emotional attachment to the way things are done at the moment. I imagine that it takes strong leadership skills to overcome such challenges. If you face this problem (and you’re sure that the practices you propose actually are the best ones) you may want to take a course in influencing people along with your studies in professional practice. As for me, I’m fortunate that I work with like-minded people. Assuming my colleagues don’t think that I’m one of those…

Conclusion

First, I see that there are two directions from which my behavior is influenced:

  • From within – by my own assumptions and feelings and understanding
  • By my external environment – the systems and relationships that surround me

I recognize that I need to deal with both of these areas.
Second,  it seems that professional quality is not a technical problem but a people problem. To develop it, I need to develop myself and my relationships with the people around me. Which is interesting in itself. The reason I got into technology because I didn’t really see myself as a people-person. It seems I was mistaken: I’m do a technical job, so I must be a people-person after all.

Naming Things

Naming Matters

For programmers, naming is an important activity:

  • It has a significant impact on code readability
  • We do it a lot

General Principles

  • Don’t make me think
  • Make wrong things look wrong
  • Take time to go fast

General Guidelines

  • Don’t be a perfectionist – don’t let naming paralize you
  • If you can improve it, do so
  • Remove the comment and improve the name
  • The wider the scope the longer the name

Follow Standards

  • Follow platform conventions
  • Call things the same as they are usually called
  • Use programmer speak for programmer things (solution domain)
  • Use the customer’s language to describe the customer’s things (problem domain)
  • Spell consistently and correctly
  • Pick one word to describe a concept and stick to it
  • Don’t inventing language where you don’t need to

Encourage Communication

  • Use pronouncable names
  • Invent language where you need to
  • Don’t be cute, clever or funny: not everyone will get it
  • Avoid cultural references

Be Useful

  • Avoid disinformation
  • Avoid noise words – words that don’t add anything (a, the etc.)
  • Avoid redundancy
  • Use searchable names
  • Think sortability – this will depend on the IDE
  • Avoid hungarian – it doesn’t usually add anything
  • Add context where it helps, remove it where it doesn’t

Specific Scenarios

  • Class names: noun-phrases, not a verbs
  • Method names: verb-phrases, not nouns

Further Reading

Data Crisis Management

A few notes on how we are managing a data crisis:

Communication

  • Who do we need to tell?
  • What do we need to tell them?
  • When do we need to tell them?

Impact Analysis

  • Who is affected?
  • To what extend?
  • What are the consequences?

Resolution

  • Do we fix everything in a systematic way or deal with the problem on an ad-hoc basis when people tell us it is a problem for them?
  • What should we prioritise?

 
 

BizTalk: Problem starting file receive location

The Problem

I was having trouble getting a receive location started. Every time I attempted to start the receive location an error message was added to the event log and the receive location remained stopped. The error message was something like this:
The receive location "<PortName>" with URL "<FileLocation>" is shutting down. Details:"The Messaging Engine failed while notifying an adapter of its configuration. ".
The transport type of this receive location is FILE.

The Solution

I’ve encountered this several times before. The solution was to make sure that the <FileLocation> exists and that the security principle under which the receive location is running actually has permission to access the receive location. Once I did this, the receive location started first time.

Can't Open BizTalk Project in VS2008

If your VS2008 BizTalk developer machine looses its ability to open or create BizTalk Projects, the reason is probably that a registry key has been overwritten by an update or repair to Visual Studio. The resiltuion is to find the registry key and reset it to its correct value.
The registry key can be reset as follows:
For 32-bit versions of Visual Studio 2008, the registry key is:

HKEY_LOCAL_MACHINESOFTWAREMicrosoftVisualStudio9.0Projects{FAE04EC0-301F-11d3-BF4B-00C04F79EFBC}PossibleProjectExtensions

For 64-bit versions of Visual Studio 2008:

KEY_LOCAL_MACHINESOFTWAREWow6432NodeMicrosoftVisualStudio9.0Projects{FAE04EC0-301F-11d3-BF4B-00C04F79EFBC}PossibleProjectExtensions

Change the value from

csproj

to

csproj;btproj