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: 149

▶ Reply to This

Replies to This Discussion

Permalink Reply by Adam Davis on April 11, 2014 at 1:29pm

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.

▶ Reply to Discussion

RSS

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.

When you create a profile for yourself you get a personal page automatically. That's where you can be creative and do your own thing. People who want to get to know you will click on your name or picture and…
Continue

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.

 

Enjoy the site? Support Codetown with your donation.



InfoQ Reading List

Vercel Releases React Best Practices Skill with 40+ Performance Rules for AI Agents

Vercel has launched "react-best-practices," an open-source repository featuring 40+ performance optimization rules for React and Next.js apps. Tailored for AI coding agents yet valuable for developers, it categorizes rules based on impact, assisting in enhancing performance, bundle size, and architectural decisions.

By Daniel Curtis

Kubernetes Introduces Node Readiness Controller to Improve Pod Scheduling Reliability

The Kubernetes project recently announced a new core controller called the Node Readiness Controller, designed to enhance scheduling reliability and cluster health by making the API server’s view of node readiness more accurate.

By Craig Risi

Presentation: Platforms for Secure API Connectivity With Architecture as Code

Jim Gough discusses the transition from accidental architect to API program leader, explaining how to manage the complexity of secure API connectivity. He shares the Common Architecture Language Model (CALM), a framework designed to bridge the developer-security gap. By leveraging architecture patterns, engineering leaders can move from six-month review cycles to two-hour automated deployments.

By Jim Gough

Microsoft Open Sources Evals for Agent Interop Starter Kit to Benchmark Enterprise AI Agents

Microsoft's Evals for Agent Interop is an open-source starter kit that enables developers to evaluate AI agents in realistic work scenarios. It features curated scenarios, datasets, and an evaluation harness to assess agent performance across tools like email and calendars.

By Edin Kapić

Pinterest’s CDC-Powered Ingestion Slashes Database Latency from 24 Hours to 15 Minutes

Pinterest launched a next-generation CDC-based database ingestion framework using Kafka, Flink, Spark, and Iceberg. The system reduces data availability latency from 24+ hours to 15 minutes, processes only changed records, supports incremental updates and deletions, and scales to petabyte-level data across thousands of pipelines, optimizing cost and efficiency.

By Leela Kumili

© 2026   Created by Michael Levin.   Powered by

Badges  |  Report an Issue  |  Terms of Service