My response -- I do leave big code comments, and it's not painful because I use an outliner, and do it carefully and consistently. There's a big comment the top of each major routine, it’s like a blog, with reverse chronologic notes about each major change. At the end of the list in the first comment is an explanation of what it does, params, etc. And since it’s in an outliner, it’s all collapsed until you need to read it.#
Here's a read-only outline listing of oldschool.js, the CMS that renders this blog. If you scroll down to publishBlog and expand it, you'll see a Changes sub-outline. Expand it to see the changes, and under each change are notes.#
This format goes all the way back to the 90s believe it or not when we started coding in an outliner in Frontier. It's the way to organize internal docs. And yes they are absolutely necessary if you plan to maintain and build on the code. #
Last update: Wednesday May 4, 2022; 7:34 PM EDT.
You know those obnoxious sites that pop up dialogs when they think you're about to leave, asking you to subscribe to their email newsletter? Well that won't do for Scripting News readers who are a discerning lot, very loyal, but that wouldn't last long if I did rude stuff like that. So here I am at the bottom of the page quietly encouraging you to sign up for the nightly email. It's got everything from the previous day on Scripting, plus the contents of the linkblog and who knows what else we'll get in there. People really love it. I wish I had done it sooner. And every email has an unsub link so if you want to get out, you can, easily -- no questions asked, and no follow-ups. Go ahead and do it, you won't be sorry! :-)
