I put in a fix on some code many year back and it wasn't pretty, I did add comments along the lines "this code is a mess but it has to go in urgently - sorry in advance".
A couple of years later a developer came to me saying he was maintaining that same bit of code. Reading the comments and understanding my frame of mind actually made it easier for him to understand what was going on.
It's a lovely tool , very customizable, and it has learned a lot throughout the past 9 months. The ability e.g. to mark classes with attributes for means of performing specific code analysis on those types didn't exist end of last year. Let's see how far it goes.
Comment preview
Comments have been closed on this topic.
Markdown formatting
ESC to close
Markdown turns plain text formatting into fancy HTML formatting.
Phrase Emphasis
*italic* **bold**
_italic_ __bold__
Links
Inline:
An [example](http://url.com/ "Title")
Reference-style labels (titles are optional):
An [example][id]. Then, anywhere
else in the doc, define the link:
[id]: http://example.com/ "Title"
> Email-style angle brackets
> are used for blockquotes.
> > And, they can be nested.
> #### Headers in blockquotes
>
> * You can quote a list.
> * Etc.
Horizontal Rules
Three or more dashes or asterisks:
---
* * *
- - - -
Manual Line Breaks
End a line with two or more spaces:
Roses are red,
Violets are blue.
Fenced Code Blocks
Code blocks delimited by 3 or more backticks or tildas:
```
This is a preformatted
code block
```
Header IDs
Set the id of headings with {#<id>} at end of heading line:
## My Heading {#myheading}
Tables
Fruit |Color
---------|----------
Apples |Red
Pears |Green
Bananas |Yellow
Definition Lists
Term 1
: Definition 1
Term 2
: Definition 2
Footnotes
Body text with a footnote [^1]
[^1]: Footnote text here
Abbreviations
MDD <- will have title
*[MDD]: MarkdownDeep
FUTURE POSTS
Partial writes, IO_Uring and safety - about one day from now
Configuration values & Escape hatches - 4 days from now
What happens when a sparse file allocation fails? - 6 days from now
NTFS has an emergency stash of disk space - 8 days from now
Challenge: Giving file system developer ulcer - 11 days from now
And 4 more posts are pending...
There are posts all the way to Feb 17, 2025
RECENT SERIES
Challenge
(77): 20 Jan 2025 - What does this code do?
Answer
(13): 22 Jan 2025 - What does this code do?
Comments
I put in a fix on some code many year back and it wasn't pretty, I did add comments along the lines "this code is a mess but it has to go in urgently - sorry in advance".
A couple of years later a developer came to me saying he was maintaining that same bit of code. Reading the comments and understanding my frame of mind actually made it easier for him to understand what was going on.
About 15 years ago I was working on a PICK system. I found some code with the following comment -
"Just a bloody comma - ignore it."
I don't know, I'm still pretty annoyed :)
What tool do you use for your diagrams? Those are some pretty looking boxes and arrows :)
That's good documentation!
It's a lovely tool , very customizable, and it has learned a lot throughout the past 9 months. The ability e.g. to mark classes with attributes for means of performing specific code analysis on those types didn't exist end of last year. Let's see how far it goes.
Comment preview