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
Azure 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 RezanovPresentation: Scaling API Independence: Mocking, Contract Testing & Observability in Large Microservices Environments
Tom Akehurst explains strategies for overcoming microservice pain points like environment dependency and slow development. He advocates using realistic API simulation at scale, supported by contract testing , API observability, and GenAI integration. Learn to compose observations, simulations, and contracts to maximize confidence and reduce the toil of maintaining realistic, up-to-date mocks.
By Tom AkehurstAzure Front Door Outage: How a Single Control-Plane Defect Exposed Architectural Fragility
A recent 9-hour Azure Front Door (AFD) outage was triggered by a faulty control-plane configuration change that bypassed safety checks due to a software defect, leading to a massive blast radius and affecting M365 and Entra ID via Identity Coupling, exposing a critical architectural anti-pattern in centralized edge fabrics.
By Steef-Jan WiggersVoices Enables Fast Text-to-Speech for Java Applications
Voices, an open-source text-to-speech project, was designed for applications running on Java 17 or newer. The library requires no external APIs or manually installed software. Audio files can be generated for various languages based on dictionaries or OpenVoice. InfoQ spoke to Henry Coles, creator of Voices and Pitest.
By Johan Janssen
© 2025 Created by Michael Levin.
Powered by
