-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
d3b2b70
commit fcc6883
Showing
3 changed files
with
31 additions
and
0 deletions.
There are no files selected for viewing
31 changes: 31 additions & 0 deletions
31
content/posts/2024-self-documenting-code-is-bullshit/index.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,31 @@ | ||
--- | ||
title: "Self Documenting Code Is Bullshit" | ||
categories: ["Code"] | ||
date: 2024-07-09 | ||
image: "self-documenting-linkedin.png" | ||
social: "https://www.linkedin.com/feed/update/urn:li:activity:7216431564308541440/" | ||
--- | ||
|
||
Hopefully, every development team reaches a point where they discuss their guidelines and policies. Part of this discussion, hopefully, includes expectations around documentation. | ||
|
||
So far, so good. Unfortunately, many teams (and I have made this mistake in the past as well) take the easy route and claim they don't need extensive documentation if they write self-documenting code. Besides the fact that this is just an easy way to avoid a discussion (because everyone interprets this differently), it is just plain wrong. Let's debunk this myth. | ||
|
||
## I Call Bullshit | ||
|
||
If users have to read a method's code before they can use it, that's not an abstraction! Good abstractions must be documented outside the actual code, or they do not abstract anything at all. | ||
|
||
![](self-documenting-post.png) | ||
|
||
## Implementation Documentation for Precision | ||
|
||
Documentation should be as close as possible to the code for the nitty-gritty details. At the bottom level, this includes variable units, boundary conditions, null value implications, resource management, and invariants. These specifics are essential to ensure a precise understanding and correct code usage. | ||
|
||
## Interface Documentation for Abstractions | ||
|
||
Striking the right balance with documentation is crucial. Interfaces should not be cluttered with implementation details. Instead, higher-level comments should enhance intuition by explaining concepts and the rationale behind the design. | ||
|
||
## Central Documentation for Cross-Module Design Decisions | ||
|
||
Ultimately, more than code alone will be required for documenting cross-module design decisions. I prefer central documentation referencing all relevant code sections, such as "See XYZ" annotations. This centralized approach ensures that anyone can understand the broader design context, which can only be captured partially through code. | ||
|
||
True clarity comes from well-placed comments and good documentation at the right level. |
Binary file added
BIN
+121 KB
content/posts/2024-self-documenting-code-is-bullshit/self-documenting-linkedin.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+116 KB
content/posts/2024-self-documenting-code-is-bullshit/self-documenting-post.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.