Comments successful your codification are the simplest and often astir useful intends of documenting your decisions and communicating intent for those that request to understand it successful the future.
However, 1 must beryllium observant to guarantee that the comments 1 leaves down are not noisy aliases misleading. My wide accuracy erstwhile it comes to comments is arsenic follows:
Never show maine what, sometimes show maine why, ever show maine why not.
As pinch each things successful software, this rule is not difficult and fast, but a wide heuristic.
What does that mean concretely?
The easiest measurement to explicate this is by example. Imagine we are penning a mini helper usability for filtering inactive users retired of a database of users we are pulling from our database.
Never show maine what
Do not explicate concepts aliases approaches that a seasoned programmer looking astatine the codification tin plainly understand. This is thing I often spot novice programmers do - they task their deficiency of comprehension of the basics onto the scholar successful the shape of over-documented code.
const getActiveUsers = (users: User[]) => { // Iterate done each of the users and cheque whether their `isActive` spot is true. return users.filter(({ isActive }) => !!isActive) }This remark is useless for anyone pinch a mean knowing of Typescript syntax and idioms. It is the breadstuff and food of the language.
Sometimes show maine why
Usually, erstwhile you are doing thing that violates the Principle of Least Surprise, you should see explaining to maine why you’ve made that decision.
const getActiveUsers = (users: User[]) => { // We request to select retired inactive users present because we don't person a DB scale connected the `isActive` field. Filtering present keeps latency down astatine the disbursal of little full, aliases perchance quiet pages return users.filter(({ isActive }) => !!isActive) }This is importantly better. As a reviewer, I understand why we’re doing thing nasty that should really beryllium handled by the database.
If I travel backmost to this successful 6 months and the scale has been provisioned, I now understand why we needed this and why it’s nary longer necessary. I americium empowered to region this nasty codification because I understand why it existed successful the first place.
Always show maine why not
If location is an evident solution to a problem which you person deliberately avoided, you should decidedly show maine why you’ve done that. Most of the time, erstwhile I’m reviewing codification pinch “tell maine why” comments, my contiguous adjacent mobility is going to beryllium “why not X?”, if X is an evident solution to the problem.
By adding it to your comment, you’re helping maine arsenic a reviewer, and the adjacent personification who has to publication this understand why you avoided the evident fix.
const getActiveUsers = (users: User[]) => { // We request to select retired inactive users present because we don't person a DB scale connected the `isActive` field. Filtering present keeps latency down astatine the disbursal of little full, aliases perchance quiet pages // Ideally we'd conscionable proviso the scale and region the request for this. We're adding this arsenic a stop-gap measurement arsenic a backend deploy is quicker than a migration to adhd an index. Adding the scale is tracked successful XXX-123 return users.filter(({ isActive }) => !!isActive) }This is highly useful arsenic I now understand why you’ve avoided the evident fix. If I travel crossed this successful the early I tin way whether the evident hole was ever actioned, and if not, perchance action it myself.
I person expressed the sentiments successful this station a fewer times passim my career, and beautiful overmuch ever successful the position described above. This conception is simply a caller introduction to the accuracy owing to a peculiar conceit of LLMs: utilizing comments arsenic a measurement of communicating pinch their handler.
These are astir apt the worst comments imaginable arsenic they connection nary awesome beyond the convention successful which they were created, are old by the clip the codification successful mobility is reviewed, and are putrid by the clip different scholar comes crossed them. They look for illustration this:
const getActiveUsers = (users: User[]) => { // FIX: The database furniture returned inactive users, filtering them present stops inactive users appearing connected the admin dashboard. return users.filter(({ isActive }) => !!isActive) }This gives maine a large dose of what, a mini broadside serving of why, and perfectly nary “why not”.
English (US) · 
Indonesian (ID) · 
