1
vote
2answers
150 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
7answers
523 views

Commenting regular expressions

Are there any common practises for commenting the regular expressions: inline comments referring different part of RegEx or general comment for all expression?
1
vote
4answers
392 views

Is extensive documentation a code smell? [closed]

Every library, open-source project, and SDK/API I've ever come across has come packaged with a (usually large) documentation file, and this seems contradictory to the wide-spread belief that good code ...
4
votes
3answers
178 views

What could be some pitfalls in introducing a style guide and documentation generating software in a development team?

I'm considering using appledoc, a flavor of Doxygen for use in generating Objective-C code documentation, in order to create documentation for my company's iOS apps. The idea is that a server will ...
8
votes
7answers
561 views

Commenting/In-Code Documentation Styles

This might be a stupid question, but it's been in the back of my head for a while and I can't find a decent answer anywhere else. I have a teacher who says we should explicitly list each parameter ...