17
votes
4answers
1k views

How to document the high-level structure of a Java program?

Background: My collaborators and I are writing an article for an academic journal. In the course of our research, we wrote a simulation program in Java. We want to make the simulation program freely ...
1
vote
1answer
113 views

Use of # in answers/documentation when referring to methods of a class

When looking through Java documentation or answers for Stack Overflow / programming forum questions, I often see people referring to methods like String#format, Object#clone etc, rather than ...
1
vote
2answers
272 views

When to write software project documentation on code [duplicate]

I usually write my software projects in java, and I am still a bit confused as to when to document my classes, interfaces and methods. There are two ways: 1) Write documentation after declaring or ...
14
votes
4answers
866 views

Documenting mathematical logic in code

Sometimes, although not often, I have to include math logic in my code. The concepts used are mostly very simple, but the resulting code is not - a lot of variables with unclear purpose, and some ...
1
vote
2answers
136 views

Is repeating links to the same class in a single javadoc comment a bad practice?

I'm currently writing an API and its documentation. For example I have something like this: public interface Event { } public interface Process { } public interface EventProcessor { /** * ...
6
votes
2answers
244 views

What's a good length for Javadoc for a class that is say 800 lines long?

I'm doing a code-review on someone's code for class. The class is about 800 lines long, contains a good dozen of functions but the description is like 1 line long. I'm wondering, generally ...
2
votes
1answer
463 views

A better JavaDoc? [closed]

The standard JavaDoc template(Doclet) didn't change much until the recent JDK7. In my opinion, JDK7 template only made it even more difficult to browse. I looked at several third-party doclets, but ...
4
votes
2answers
533 views

Explaining how the code you wrote works [closed]

I was asked to create for a freelance project a Monopoly game in Java. After finishing it the same guy asked me to create four UML diagrams from which he could understand how the game works. ...
11
votes
6answers
2k views

Self-documenting code vs Javadocs?

Recently I've been working on refactoring parts of the code base I'm currently dealing with - not only to understand it better myself, but also to make it easier for others who are working on the ...
6
votes
2answers
2k views

Backend programming portfolio

For most of my development years I have been a Java backend developer, mostly for web applications. Usually for regular jobs I have described my duties in previous ones during the interview, expanding ...
7
votes
1answer
647 views

How to document an algorithm properly with sample data?

I am wondering what should an algorithm documentation contain? Can't locate a proper guideline to follow. I have in mind to include summary of the algorithm description of the algorithm flowcharts ...
3
votes
2answers
105 views

What can I use to generate API documentation with my custom formatting?

I want to automatically generate documentation for a java project, but I'd like to have my own custom styling for it. As an example, take the stackoverflow api (method description page), can that be ...
1
vote
2answers
284 views

Taking part in an open source project [duplicate]

I am new to open source development. I want to add some functionality to an open source project PRISM. But I couldn't find any developer guide or code architecture guide sort of a thing for it. How ...
5
votes
7answers
874 views

Is it wrong not to create Javadoc for my code?

I do a lot of Java programming at my work (I'm an intern) and I was wondering if it is generally a rule to create javadoc to accompany my code. I usually document every method and class anyways, but I ...
7
votes
6answers
2k views

Is it necessary to write a javadoc comment for EVERY parameter in a method's signature?

One of the devs on my team believes that it is necessary to write a javadoc comment for EVERY parameter in a method's signature. I do not think this is necessary, and in fact I think it can even be ...
0
votes
2answers
2k views

PDF or ebook Java API documentation [closed]

Since I have a long train ride to and from work I was wondering if there is a version of the Java API documentation floating around that I could put on my Kindle. It would be nice on the rare occasion ...
9
votes
9answers
443 views

Studies on code documentation productivity gains/losses

After much searching, I have failed to answer a basic question pertaining to an assumed known in the software development world: WHAT IS KNOWN: Enforcing a strict policy on adequate code ...