Gallery
Kuovonne's Guide to Scripting in Airtable
Share
Explore
Developing Generic Coding Skills

Comments in Code

Your donations tell Kuovonne that you value her content and want her to continue publishing.

How to use comments

Novice coders tend to write comments that translate what the code does into English. However, if the code is well written, an experienced coder should be able to tell what the code does from the code itself, and the novice’s comments are extra text that gets in the way or has to be maintained.
Use comments to highlight the structure of the code between functions
Use comments to explain why the code was written a particular way instead of a simpler alternative.
Use comments to give credit when using someone else’s code
Delete commented-out code before considering that section of code complete.

Why less is better

Maintaining comments is extra work that is easily forgotten.
Obsolete or incorrect comments are worse than no comments.
Do not use comments as a crutch for an inability to read code — learn to read code.
Do not use comments as a crutch for poorly named variables or bad organization.

Meta information

Self-contained files that will be published publicly may have a header section with comments that include meta information
name of the code
purpose of the code
author
revision date
license for reusing the code
any special instructions for using the code
revision history
For files that are stored in a source control repository, this meta information is typically available in the repository itself and need not be included in the file.
The content in this guide is free, but creating it takes time and money. If you like this content, .

Share
 
Want to print your doc?
This is not the way.
Try clicking the ⋯ next to your doc name or using a keyboard shortcut (
CtrlP
) instead.