Codetown
Codetown ::: a software developer's community
Documentation standards or guidelines?
Does anyone care to share their suggestions for documentation?
I'm asking because I recently had to change a program I wrote more than five years ago. I'd always thought that I've done a good job of documentation. But going through it was difficult. It WAS pulling apart an Excel in CSV format created and saved off by humans, so there was a lot of exception handling. But still . . . .
- Miek
Views: 153
Replies to This Discussion
-
Permalink Reply by Adam Davis on
-
Generally I only put javadocs on public methods, especially ones that are used a lot. I use code comments sometimes, but generally if the code is hard to understand I take that as a "smell" that means you need to break down the code into more methods, refactor, or think about better naming.
Happy 10th year, JCertif!
Notes
Welcome to Codetown!
Codetown is a social network. It's got blogs, forums, groups, personal pages and more! You might think of Codetown as a funky camper van with lots of compartments for your stuff and a great multimedia system, too! Best of all, Codetown has room for all of your friends.
Created by Michael Levin Dec 18, 2008 at 6:56pm. Last updated by Michael Levin May 4, 2018.
Looking for Jobs or Staff?
Check out the Codetown Jobs group.
InfoQ Reading List
VoidZero’s Experimental Oxc Angular Compiler with Up to 20x Faster Build Performance
VoidZero has released an experimental Angular compiler in Rust, promising improved build performance compared to Angular CLI. Benchmarks indicate it is up to 6.4x faster than Angular CLI, especially for larger applications. Developed over two months with AI collaboration, it integrates with Vite and offers significant reductions in build time. The initiative is for research purposes only.
By Daniel CurtisMicrosoft Releases .NET 11 Preview 3 with Updates Across Runtime, SDK, MAUI, and ASP.NET Core
Microsoft has released .NET 11 Preview 3, the third preview of its upcoming Standard Term Support version due in November 2026. The update spans the runtime, SDK, libraries, ASP.NET Core, EF Core, and .NET MAUI, with Runtime Async leaving the preview-feature gate, new JIT optimizations, Zstandard compression in ASP.NET Core, and expanded MAUI Map controls.
By Almir VukPresentation: Agents, Architecture, & Amnesia: Becoming AI-Native Without Losing Our Minds
Tracy Bannon shares a cautionary tale of "The Sorcerer’s Apprentice" to illustrate the risks of unbridled AI autonomy. She discusses the shift from bots to autonomous agents, explaining how reckless speed leads to "Architectural Amnesia." She provides a concrete framework for "Minimum Viable Governance," focusing on identity, delegation, and ADRs to manage debt at machine speed across the SDLC.
By Tracy BannonSauce Labs Launches AI Agent to Automate Test Creation and Close the DevOps “Velocity Gap”
Sauce Labs has announced the general availability of Sauce AI for Test Authoring, an AI-driven agent designed to translate business intent directly into executable test suites, marking a shift toward what the company calls Intent-Driven Testing.
By Craig RisiMistral AI Introduces Workflows for Orchestrating Enterprise AI Processes
Mistral AI has launched Workflows, an orchestration layer for enterprise AI that is now in public preview. This release addresses a significant challenge as AI models and agents become more advanced, while reliably deploying them in production remains difficult due to a lack of infrastructure for coordination, monitoring, and recovery.
By Robert Krzaczyński
© 2026 Created by Michael Levin.
Powered by
