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: 151
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
PyPI Supply Chain Attack Compromises LiteLLM, Enabling the Exfiltration of Sensitive Information
Discovered by FutureSearch researcher Callum McMahon, a supply chain attack against LiteLLM on PyPI resulted in over 40 thousand downloads of a compromised version that installed a malicious payload capable of harvesting and exfiltrating sensitive information. LiteLLM is downloaded roughly 3 million times per day.
By Sergio De SimoneAgentic AI Patterns Reinforce Engineering Discipline
Paul Duvall recently discussed his library of engineering patterns for AI assisted development and practices that ground high quality delivery. Related discussions from Paul Stack and Gergely Orosz highlight a shift toward remixing and specification driven development.
By Rafiq GemmailPresentation: Hidden Decisions You Don’t Know You’re Making
Dan Fike and Shawna Martell explain how "hidden decisions" silently shape software architecture and engineering culture. By examining the invisible defaults behind CI/CD bottlenecks, platform complexity, and misaligned metrics, they share frameworks for leading with intentionality. Learn to identify the "decision behind the decision" to better incentivize high-performing teams and careers.
By Shawna Martell, Dan FikeKubernetes Autoscaling Demands New Observability Focus Beyond Vendor Tooling
As adoption of Kubernetes autoscalers like Karpenter accelerates, a new set of platform-agnostic observability practices is emerging, shifting focus from traditional infrastructure metrics to deeper insights into provisioning behavior, scheduling latency, and cost efficiency.
By Craig RisiTanStack Start Introduces Import Protection to Enforce Server and Client Boundaries
TanStack Start has introduced a import protection, which aims to prevent server and client code from being mixed in full-stack React applications. This Vite plugin automatically checks imports during development and build processes. It blocks harmful imports by file naming conventions or explicit markers, enhancing security and reducing bugs without requiring additional developer input.
By Daniel Curtis
© 2026 Created by Michael Levin.
Powered by
