News for hackers. Stuff that matters.
Re:Changing how I review code by LeftHandPath on Wednesday June 30, 2021 @08:50PM (#27695227)
At work, I've been writing a word document to explain every part of a program I've written and how each element interacts with the rest. It's been very helpful to find things that don't make as much sense as I thought they did when I wrote them, and revealing old code that is no longer used anywhere in the application. And I've caught a few places where outdated .txt / .md / inline-doxygen documentation lies, too.

Writing a summary document really forces you to get to the nitty gritty and catch things that a casual review would miss.

Re:Changing how I review code by chii on Wednesday June 30, 2021 @10:44PM (#27695796)
But wouldn't this summary document be better as a form of comment in the source code rather than a separate document that will become out of date the next time someone else makes changes?
Re:Changing how I review code by KronisLV on Thursday July 01, 2021 @02:26AM (#27696791)
Furthermore, wouldn't a Markdown document be a bit better as opposed to Word? That way, you or anyone else could easily search through its contents alongside the rest of the codebase, were it to be included in the repository, whereas that wouldn't work with Word, because it's a proprietary and binary format (unless you open that file in particular).