Tagged Questions
1
vote
1answer
49 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 {
/**
* ...
1
vote
4answers
374 views
Creating a coding standards document
I work in a control systems company, where the primary work is SCADA and PLC, along with other control systems stuff.
Softwre development is not really something the company does, apart from little ...
6
votes
3answers
397 views
Are XML Comments Necessary Documentation?
I used to be a fan of requiring XML comments for documentation. I've since changed my mind for two main reasons:
Like good code, methods should be self-explanatory.
In practice, most XML ...
1
vote
4answers
248 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 ...
3
votes
3answers
207 views
How to be productive as an infrequent programmer?
My current day job is mostly project management and client liaison work, but I sometimes get involved in actual coding. I do this either because I have a clear vision of what I want the result to look ...
53
votes
17answers
3k views
How to deal with tautology in comments?
Sometimes I find myself in situations when the part of code that I am writing is (or seems to be) so self-evident that its name would be basically repeated as a comment:
class Example
{
/// ...
25
votes
8answers
1k views
Is there such a thing as having too many private functions/methods?
I understand the importance of well documented code. But I also understand the importance of self-documenting code. The easier it is to visually read a particular function, the faster we can move on ...
