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

▶ 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

pnpm 11 Release Candidate: ESM Distribution, Supply Chain Defaults and a New Store Format

pnpm 11 RC has been released, featuring significant changes in performance, security, and configuration. Key updates include an SQLite-backed store index, tighter security defaults, and a consolidated build script setting. It now requires Node.js v22 or later. Global installs are isolated by default, and new commands enhance usability. Migration guidance is available in the documentation.

By Daniel Curtis

Anthropic Introduces Managed Agents to Simplify AI Agent Deployment

Anthropic introduces Managed Agents on Claude, a managed execution layer for agent-based workflows. It separates agent logic from runtime concerns like orchestration, sandboxing, state management, and credentials. The system supports long-running multi-step workflows with external tools, error recovery, and session continuity via a meta-harness architecture.

By Leela Kumili

Slack Rebuilds Notification System, Reports 5X Increase in Settings Engagement

Slack has rebuilt its notification system with a unified architecture that separates activity from delivery, improving consistency across platforms. The redesign simplifies preferences, preserves legacy settings through transformation, and resulted in a 5x increase in user engagement with notification settings along with reduced support tickets.

By Leela Kumili

GitHub Acknowledges Recent Outages, Cites Scaling Challenges and Architectural Weaknesses

GitHub has publicly addressed a series of recent availability and performance issues that disrupted services across its platform, attributing the incidents to rapid growth, architectural coupling, and limitations in handling system load.

By Craig Risi

Presentation: Dynamic Moments: Weaving LLMs into Deep Personalization at DoorDash

Sudeep Das and Pradeep Muthukrishnan explain the shift from static merchandising to dynamic, moment-aware personalization at DoorDash. They share how LLMs generate natural-language "consumer profiles" and content blueprints, while traditional deep learning handles last-mile ranking. This hybrid approach allows the platform to adapt to short-lived user intent and massive catalog abundance.

By Sudeep Das, Pradeep Muthukrishnan

© 2026   Created by Michael Levin.   Powered by

Badges  |  Report an Issue  |  Terms of Service