Writing comments

It's good practice to add comments to any code to explain what it's doing to the curious (or debugging) reader, and Bash is no exception. Keep your comments concise, up-to-date, and most of all, useful. Remember: don't just rephrase what the code is doing; explain why you're doing it, not just what it does.

Consider this comment and line of shell script:

# Loop to end of positional params
for targetdir ; do : ; done

Is the comment here helpful to someone reading the script? Can you tell what the code is doing? Consider the following comment instead, which explains the purpose of the unclear code, even to a user who may not do much shell programming:

# Save last command line argument as target directory for targetdir ; do ...

Get Bash Quick Start Guide now with the O’Reilly learning platform.

O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.