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: 137
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
Inside Uber’s Pinot Query Overhaul: Simplifying Layers and Improving Observability
Uber rebuilt its Apache Pinot query architecture, replacing the Presto-based Neutrino system with a lightweight proxy called Cellar and Pinot’s Multi-Stage Engine Lite Mode. The redesign simplifies SQL execution, improves resource management, and ensures predictable performance for large-scale analytics workloads.
By Leela KumiliGrafana and GitLab Introduce Serverless CI/CD Observability Integration
In a move to streamline development workflows, Daniel Fritzgerald of GrafanaLabs has published a new open-source solution that links GitLab CI/CD events into Grafana's observability stack via a serverless architecture.
By Craig RisiHow AI with Prompt Engineering Supports Software Testing
AI is becoming a key QA tool, aiding in faster scenario generation, risk detection, and test planning. Arbaz Surti showed how effective prompting using roles, context, and output format helps to get clear, relevant, and actionable test scenarios. AI can boost testers, but human judgment is needed to ensure relevance and quality.
By Ben LindersAzure APIM Simplifies Event-Driven Architecture with Native Service Bus Policy
Microsoft's new feature in API Management (APIM) enables seamless messaging to Azure Service Bus, simplifying API connections in event-driven architectures. By using the send-service-bus-message policy, developers can easily route HTTP requests to Service Bus for asynchronous processing, enhancing integration, security, and control without additional components.
By Steef-Jan WiggersArticle: Training Data Preprocessing for Text-to-Video Models
In this article, author Aleksandr Rezanov discusses the data preparation for generative text-to-image models to accelerate work on video generation services to be used in TV series and films. He explains how data is prepared and can serve as a starting point for creating custom datasets to develop proprietary models.
By Aleksandr Rezanov
© 2025 Created by Michael Levin.
Powered by
