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: 150
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
DoorDash Builds LLM Conversation Simulator to Test Customer Support Chatbots at Scale
DoorDash engineers built a simulation and evaluation flywheel to test large language model customer support chatbots at scale. The system generates multi-turn synthetic conversations using historical transcripts and backend mocks, evaluates outcomes with an LLM-as-judge framework, and enables rapid iteration on prompts, context, and system design before production deployment.
By Leela KumiliNetflix Uncovers Kernel-Level Bottlenecks While Scaling Containers on Modern CPUs
Engineers at Netflix have uncovered deep performance bottlenecks in container scaling that trace not to Kubernetes or containerd alone, but into the CPU architecture and Linux kernel itself.
By Craig RisiPresentation: Beyond the Code: Hiring for Cultural Alignment
Alicia Collymore discusses the critical role of cultural alignment in building high-performing engineering teams. She explains how to move beyond "vibes" by identifying specific attributes in company values and assessing them during coding challenges and system design sessions. She shares practical advice on using interview debriefs, assessment criteria, and "culture add" to drive growth.
By Alicia CollymoreArticle: The Oil and Water Moment in AI Architecture
Have you ever tried mixing oil and water? That is the moment software architecture is entering as deterministic systems meet non deterministic AI behaviour. Architects must anchor intelligent systems in intent, governance and systems thinking. This article introduces the Architect’s V Impact Canvas, a framework for navigating this shift while keeping human trust at the centre.
By Shweta VohraPodcast: Information Flow: The Hidden Driver of Engineering Culture
In this podcast, Shane Hastie, Lead Editor for Culture & Methods, spoke to Adrian Peryer about Ron Westrum's organizational culture continuum, the role of information flow in shaping team culture, and how leaders can develop requisite imagination to detect weak signals.
By Adrian Peryer
© 2026 Created by Michael Levin.
Powered by
