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: 135
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
New DNS Armor Service Helps Google Cloud Workloads Preemptively Block Cyber Threats
Google Cloud's DNS Armor, in partnership with Infoblox, offers a vital layer of security against DNS-based threats for Google Cloud workloads. Utilizing advanced threat detection and machine learning, it identifies and mitigates risks like malware and data exfiltration, ensuring robust protection without impacting performance. Deployable as a managed service providing seamless control for users.
By Steef-Jan WiggersVercel Introduces Drains for Unified Data Export
Vercel has released Vercel Drains, a system for exporting observability data from its platform into external services. The feature unifies logs, distributed traces, web analytics events, and performance metrics into a single streaming mechanism.
By Daniel DominguezAWS Introduces M4 and M4 Pro Mac Instances for Faster Apple App Development
AWS has recently launched two new Mac instances (M4 and M4 Pro) built on Apple's latest M4 silicon. The new EC2 instances provide faster CPU performance, enhanced graphics, and increased memory for building iOS and macOS applications.
By Renato LosioAgoda Leverages ChatGPT in the CI/CD Process for SQL Stored Procedure Optimization
Agoda started utilizing ChatGPT to optimize SQL stored procedures (SP) as part of their CI/CD process. After introducing the automated LLM-assisted step, the company observed shortened stored procedure optimization times, which lightened the load on DB developers. Agora works on making ChatGPT more accessible for SP optimization outside of the CI/CD pipeline.
By Rafal GancarzPresentation: Scaling the BBC Design System: Tooling, Community, Governance and Gardening
Sophie Beaumont shares how the BBC's web design system supports over 10 brands and 25 engineering teams, handling 4.8 billion requests monthly. She explains their federated contribution model, which combines automation, mandatory ownership, and a collaborative gardening approach to create a scalable, maintainable, and highly accessible system.
By Sophie Beaumont
© 2025 Created by Michael Levin.
Powered by
