Code Documentation: unleash the senior developer inside you

Photo by Patrick Tomasso on Unsplash

“Any fool can write code that a computer can understand. Good programmers write code that humans can understand.” — Martin Fowler

As Martin Fowler said, developers are meant to write a code that other developers can read, clean, refactor, maintain and add to it.

Code documentation is a key actor in the process of creating the piece of code that you can post it on the louvre museum.

“In some ways, programming is like painting. You start with a blank canvas and certain basic raw materials. You use a combination of science, art, and craft to determine what to do with them.” — Andrew Hunt

So in this article we will see how code documentation is really useful and what are the rules of creating a good code documentation.

The examples in this article will be with Dart / Flutter but the idea behind code documentation and the rules are the same in any other technology.

What Is Code Documentation ?

“Code documentation is text that accompanies software code to explain what your code is doing, why it’s written the way it is, and/or how to use it” — Toby Osbourn (what is code documentation)

In other terms code documentation is a bench of code comments and/or markdown files supporting the code to ease the maintaining of the code in the future.

Code documentation can be in form of comments alongside the code or can be separated in files (markdown files for example).

Is self-Documenting code a solution ?

When searching for the best code qualities the first thing you may find is that the code itself need to be understandable so you don’t have to explain it, but for junior developers solving the problem or creating the feature itself is time consuming so you don’t find enough time to clean up the mess even for some senior developers they end up writing bad-quality code.

Self-documenting code is the best option to get rid of documenting each function, but it’s rare even self-documenting code need to be documented to explain each parameter’s utility for example, because not every developer that will face the code will understand your logic.

In the end the goal is to maintain the code quality whoever the developer that may work on it so you need to guarantee that every developer can understand what you are writing.

How we document our code ?

Conventions

• Do format comments like sentences.

Capitalize the first word unless it’s a case-sensitive identifier. End it with a period , “!”, “?”

• Don’t use block comments for documentation like shown in the example below

/* Assume we have a valid name. */
  print('Hi, $name!');

• Use the appropriate comment syntax:

in every language we have syntax to write comments (python with #, Java with //…)

in every language we have also the appropriate syntax to write code documentation

in Java :

/**
* code documentation goes here
*/
void  displayName(String name){
  System.out.println(name);
}

• Start doc comments with a single-sentence summary

for example instead of doing :

/// Depending on the state of the file system and the user's permissions,
/// certain operations may or may not be possible. If there is no file at
/// [path] or it can't be accessed, this function throws either [IOError]
/// or [PermissionError], respectively. Otherwise, this deletes the file.
void delete(String path) {
  ...
}

it’s better and prefered to do this, even it’s more readable and clear

/// Deletes the file at [path] from the file system.
void delete(String path) {
  ...
}

• Seperate the first summary sentence into its own paragraph

it’s recommended to seperate the first sentence that contains the summary from the rest of the documentation, this help tools like dartdoc, javadoc and others to generate more clear doc files.

example:

/// Deletes the file at [path].
///
/// Throws an [IOError] if the file could not be found. Throws a
/// [PermissionError] if the file is present but could not be deleted.
void delete(String path) {
  ...
}

• Focus on what the reader dosen’t know, Avoid redundancy

class RadioButtonWidget extends Widget {
  /// Sets the tooltip for this radio button widget to the list of strings in
  /// [lines].
  void tooltip(List<String> lines) {
    ...
  }
}

As you see in the example above the class name and the class members are clearly obvious so it’s unecessary to mention that in the doc.

Example:

class RadioButtonWidget extends Widget {
  /// Sets the tooltip to [lines], which should have been word wrapped using
  /// the current font.
  void tooltip(List<String> lines) {
    ...
  }
}

• Start functions with third-person verbs

/// Returns `true` if every element satisfies the [predicate].
bool all(bool predicate(T element)) => ...

/// Starts the stopwatch if not already running.
void start() {
  ...
}

• Doc for variables starts with noun phrases

/// The current day of the week, where `0` is Sunday.
int weekday;

How we use dartdoc ?

Dartdoc is documentation generator tool, it uses the code documentation written to generate html files containing a beautifull-designed classes, methods, variable and api documentations.

Installation

to install dartdoc in your pc all you need to do is to execute the command below

pub global activate dartdoc

or

flutter pub global activate dartdoc

for some you may encouter a problem says that dartdoc isn’t known as an internal command, in this case just add <complete_path>\flutter\.pub_cache\bin, example C:\FLUTTER\.pub-cache\bin

• Linux

export PATH=FLUTTER/.pub-cache/bin:$PATH

• Windows 10:

https://stackoverflow.com/questions/44272416/how-to-add-a-folder-to-path-environment-variable-in-windows-10-with-screensho

• Windows 11:

Step 1: Right click on “This pc” in file explorer

Step 2: click on “Properties”

Step 3: Click on “Advanced system settings”

the next steps are the same as Windows 10.

usage

to generate project documentation files you need first to analyze your code with “flutter analyze” or “dart analyze”

and then launch the command

dartdoc

in your project file. and then a new folder has been added to your project called api contains all the HTML documentation files

for more detailed information about the api folder content please check the link below

dartdoc | Dart Package

Conclusion

As we saw in this article, code documentation is essential part that you need to add to keep your code alive and explain to other developers or even you in the future (developers are the most forgetful creatures 🤣) the logic of the algorithm.

for learn more about code documentation you can check the links below

https://textexpander.com/blog/code-documentation#:~:text=Code%20documentation%20is%20text%20that,supporting%20documentation%20about%20the%20code.

https://www.writethedocs.org/guide/writing/beginners-guide-to-docs/

10 Tools for the Perfect Code Documentation