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: 131
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
DevProxy 0.25 Improves Configuration Management, Joins .NET Foundation
Microsoft has released version 0.25 of DevProxy, an API simulation command-line tool. The new version improves the tool's configuration management and adds a couple of usability features. The project is also added to the .NET Foundation, a non-profit organisation to support the .NET platform ecosystem.
By Edin KapićArticle: Beyond Notebook: Building Observable Machine Learning Systems
In this article, author discusses a machine learning pipeline with observability built-in for credit card fraud detection use case, with tools like MLflow, FastAPI, Streamlit, Apache Kafka, Prometheus, Grafana, and Evidently AI.
By Lakshmithejaswi NarasannagariPresentation: Dare Mighty Things: What NASA's Endeavors Teach Us About the Power of Calculated RISCs
Khawaja Shams explores the essence of calculated risks, discussing why taking these risks, how to identify and mitigate potential downsides, and the characteristics of good risks.
By Khawaja ShamsPodcast: Engineering Culture and the API Revolution: A Conversation with Sagar Batchu
In this podcast, Shane Hastie, Lead Editor for Culture & Methods spoke to Sagar Batchu about building engineering teams in different environments, the transition from individual contributor to leadership roles, the importance of culture and autonomy in organizations, and the implications of AI agents on the future of APIs.
By Sagar BatchuGoogle Cloud's AI Protection: a Solution to Securing AI Assets
Google Cloud introduces AI Protection, a solution to safeguard against generative AI threats. Managing AI risks through vulnerability assessments, security policies, and proactive threat management enhances asset protection. Integrating with Google’s Security Command Center offers a centralized view of IT posture and advanced security intelligence for robust AI system defense.
By Steef-Jan Wiggers
© 2025 Created by Michael Levin.
Powered by
