Comments as first class citizens

In the future it will be possible to link comments to sections of code, instead of just writing them a couple of lines above of it. Today, comments are second-class citizens that frequently get out of sync with the reality of the code. This is because working on code is done when the brain is in spotlight mode: we first look at this piece of code, which calls this function, which calls this method, etc. . The brain jumps from line to line, and misses the context around it. Documentation and comments are more holistic and should not be in-line with code, as they are something different entirely. Comments are "about" the code, not code itself.

In a merge request, you should see the changed piece of code with the comments that are applicable to it. These can be locally (like the comments that today are in the same file), but also an architecture document could refer to sections of code that implement the architecture. In the IDE, and certainly in a merge request, the developers should see if their changes still match the documented functionality and architecture.

Tools like Code Lens slowly get us into the right direction.

Popular posts from this blog

UUIDs in MySQL are really not random

Parsing 10TB of Metadata, 26M Domain Names and 1.4M SSL Certs for $10 on AWS

S3 boto3 'StreamingBody' object has no attribute 'tell'