Sunday, 27 October 2013

7 reasons why naming is important

Giving things a good name is incredibly important. This article explains 7 reasons why naming is important and how those same principles apply to Javadoc or any other kind of code documentation.

The name...

  1. ... is the first thing people will see.

  2. ... is the only thing people will definitely read.

  3. ... is therefore the most important piece of documentation!
    All other documentation suffers from a single problem: people don't read it. This problem varies between different kinds of documentation: code comments are more likely to be read than a Wiki page, but the only thing that is guaranteed to be read by others is the name!

  4. ... is everywhere!
    Whether it's a class, a function, a variable, a package, a project, a Jenkins job or a plain filename, everything you create is your brainchild! Therefore think of the name as you would when naming your child!

  5. ... is a good Architect!
    If a good name is hard to find, it probably means that the thing you're creating is the wrong thing. On the other hand, if a good name is easy to find, it's usually a good indication of loose coupling, high cohesion and a well defined purpose of whatever it is that you're creating.

  6. ... likes its siblings.
    Whenever you're naming something, always look for an existing naming convention. Look at similar files, similar classes, methods, variables, etc. And if you don't like the convention, please don't just start a new one. When starting a new one, make sure that all existing names are updated to the new convention. Remember: multiple standards means no standard at all.

  7. ... can be a pain when wrong.
    So don't continue your work if you don't have a good name for what you're about to create. Don't choose a temporary name and refactor later, because most of the time, that refactor will never come. Also, especially in the early stages of a project, it is very important to get the architecture right and as explained above, needing a temporary name in lack of something better, is usually a sign of a bad architecture.

    Don't be alarmed when it's hard to find a good name. 10 minutes of thinking for a name or talking to 10 people for a name will be well worth it in the end. Just realize that thinking of a name is thinking about the architecture! Once you realize that, 10 minutes does not seem so long anymore.
Javadoc
Javadoc, or any other kind of code documentation (if you don't use Java, just think of the code documentation of your favourite language), is the name's big brother. When a name can't do it, Javadoc can. The same principles apply here: If it's easy to write good Javadoc, it usually indicates good architecture, loose coupling and high cohesion. Force yourself to write Javadoc before writing code! As soon as you have created that class or function, write the Javadoc for it before writing any code in it. It will prevent you from creating the wrong class or function and remember: If you can't explain your code, then you should not write it. Also think of how happy you are when other people have written Javadoc for their code!

Good Javadoc needs to have the following:

  • The purpose of the class, function or variable.

  • Every first sentence of a Javadoc block needs to end with a period. This is because the Javadoc generator uses the first sentence (i.e. the part before the first period) as a summary section to display on the generated Javadoc HTML. It is good practice to end all of your sentences with a period anyway.

  • If the class, function or variable will be used in a select number of related places, it can be useful to mention that in the Javadoc. For example: "This class is used by class X to do Y". Obviously, this should not be done if the nature of the class is generic and not directly related to any other piece of code.

  • I'm a web developer and I found that, when creating classes that correspond to certain parts of the website, it can be incredibly useful to explain where exactly on the website you can see this particular page or panel. For example: "This panel is displayed when you click on button X on page Y". Whenever you, or someone else, needs to edit that class later, it will be easier if that particular page or panel can be found easily on the site.

  • Finally, any special/peculiar things that are not immediately obvious should be in the Javadoc. Don't write things that can be trivially understood by just reading the code itself. The more words you use, the less likely it is that people will read all of it, so instead, focus on the things that need explaining. Think about what you would like to read when you would see this class for the first time.
"Keep documenting until you can watch someone else read it without feeling the need to explain anything"