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: 141
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
Uber Adopts Amazon OpenSearch for Semantic Search to Better Capture User Intent
To improve search and recommendation user experiences, Uber migrated from Apache Lucene to Amazon OpenSearch to support large-scale vector search and better capture search intent. This transition introduced several infrastructure challenges, which Uber engineers addressed with targeted solutions.
By Sergio De SimoneBenchmarking Beyond the Application Layer: How Uber Evaluates Infrastructure Changes and Cloud Skus
Uber’s Ceilometer framework automates infrastructure performance benchmarking beyond applications. It standardizes testing across servers, workloads, and cloud SKUs, helping teams validate changes, identify regressions, and optimize resources. Future plans include AI integration, anomaly detection, and continuous validation.
By Leela KumiliPresentation: Changing Power Dynamics: What Senior Engineers Can Learn From Junior Engineers
Beth Anderson discusses the "power distance index" and its critical role in communication. Using the Korean Air Flight 801 tragedy as a case study, she explains the dangers of hierarchy-driven silence. She shares actionable frameworks for building the 4 stages of psychological safety, implementing reverse mentoring, and using PRs as tools for knowledge sharing rather than gatekeeping.
By Beth AndersonPodcast: Effective Mentorship and Remote Team Culture with Gilad Shoham
In this podcast, Shane Hastie, Lead Editor for Culture & Methods, spoke to Gilad Shoham about building effective mentorship relationships, leading fully distributed teams and the evolving role of developers in an AI-augmented future.
By Gilad ShohamBeyond Win Rates: How Spotify Quantifies Learning in Product Experiments
Spotify has introduced the Experiments with Learning (EwL) metric on top of its Confidence experimentation platform to measure how many tests deliver decision-ready insights, not just how many “win.” EwL captures both the quantity and quality of learning across product teams, helping them make faster, smarter product decisions at scale. The outcome must support one action: ship, abort, or iterate.
By Olimpiu Pop
© 2025 Created by Michael Levin.
Powered by
