aizatto.com
aizatto.com
Build.my
GitHub
Linkedin
aizatto.com
Table of Contents
Portfolio, Projects, Tools, Toys
Interview Guide
Engineering Code
Communication
Different Types of Coding
Commit Messages
Reviewing Code
Writing Code
Consistency
Writing for a code base of 1,000,000+ Lines
Write Code Knowing It Will Be Refactored
Naming
Commenting
Don't commit commented code
Make It Easy To Reproduce
Scripts
80 character limit
Exit Early
Be careful of enum in switch statements
Be careful about chaining conditions
Be careful of chaining ternary operators
Write Code Knowing You Will be Blamed
Hacks
Bad Practices
Logs
Time
Other rules
Engineering Code
Engineering Data
Pipelines
Configuration Files
Site Reliability Engineering (SRE)
Best Engineers
Engineering Management
Why GitBook?
Getting into Tech
Personal Goals
Daily Drivers
Notes
AWS
Digital Ocean
GraphQL
JavaScript
Life
Node.js
Prototyping
Raspberry Pi
Serverless
Software Engineering
Technical Due Diligence
Web Development
Archive
Powered by GitBook

Commenting

Comments increase cognitive load. Comments are a form of technical debt.

There can be both good and bad comments.

Comment on the "why" things work the way they are.

Good comments:

  • Legal/regulatory explanations on why it does what it does

Leave links to other resources:

  • Wikis

  • GitHub Issues or Pull Requests

  • Documentation

If comments are long and are not critical to be in the code, create a linkable resource, and use the link instead.

Dangers of bad comments:

  • Comments can be outdated and wrong

Previous
Create Searchable Names
Next
Don't commit commented code
Last updated 1 year ago