re: Coding practices your future self will love you for VIEW POST

FULL DISCUSSION
 

Here's another one: document your code. As in write a technical documentation of your code. It doesn't necessarily mean the document should be technically technical, just make it brief and concise but provides necessary details for your future self to read and remind themselves.
Technical writing is somewhat underrated especially in open source programs, I think.

I'm currently practicing this myself with my recent projects and the (perceived) quality of my project is better than before.
Even if I'm not writing for myself, I still write with the assumption that others will read it.

 

Yes! Very important aspect!

Technical writing has always been very under-rated, but very critical. Documenting any workflow, API or algorithm helps us reason with our own assumptions and removes inconsistencies and biases.

In the open source world, documentation has the added benefit of getting new contributors interested in the project. It's also much easier to raise your first PR for a documentation fix than for an actual bug.

 

The one I'd add is (for my purposes) to the same end: docs, ideally, should be written in the same cadence as the code - update code, update doc, update code, update doc.
This is insanely turbulent for me.

Instead, I've adopted something between TDD and plain through-as-crap testing.

I can run the specs and flip through the its and get a complete understanding of what the code should (and should not) do, and how to make it do it.
Doc-by-test is much easier for me because I don't have to switch gears to keep it moving.

The "honest" benefits of testing are just byproducts lol.

code of conduct - report abuse