3

So I have been working on a C# Matrix library. I've been documenting it really good so far.

The thing is I don't know if I should document my overloaded operators, I mean, it is kind of obvious, isn't it?

Sample code:

public static Matriz operator *(Matriz A, Matriz B)
{
    if (A.map.GetLength(1) != B.map.GetLength(0))
        throw new ArgumentException("A[j] não é igual a B[i]");

    float[,] _map = new float[A.map.GetLength(0), B.map.GetLength(1)];

    for (int i = 0; i < A.map.GetLength(0); i++)
    {
        for (int j = 0; j < B.map.GetLength(1); j++)
        {
            _map[i, j] = 0;
            for (int z = 0; z < A.map.GetLength(0); z++)
            {
                _map[i, j] += A.map[i, z] * B.map[z, j];
            }
        }
    }

    return new Matriz(_map);
}
  • Document why, in comments. Document the architecture (just a few pages) in drawings and words. Keep the rest as code, because no one will read and documentation that describes what it does. The code already describes that. Experienced programmers know that the documentation is wrong, and in the rare instance that it is not wrong it says what the code says, so they will not wast time reading it. – ctrl-alt-delor Jun 29 '16 at 22:21
  • Sure, experienced programmers read the code easily. However, they tend to be architects of the project. Addition of a features,bug fixes, optimizations are done by relatively inexperienced programmers. And they will learn coding practices from you. So, please leave more comments and keep the code clear.. – sixtytrees Jun 29 '16 at 22:26
  • 2
    I disagree that I have always been an “architect of the project”, most of my experience of this issue is that I have joined a project. If there are lots of comments, then the comments tend to be wrong. If there are few comments then they tend to be correct, and worth reading. – ctrl-alt-delor Jun 29 '16 at 22:34
6

The thing is I don't know if I should document my overloaded operators, I mean, it is kind of obvious, isn't it?

Simple answer:

Then it won't take you very long to document it, will it? Just do it!

Complicated answer:

You're writing this documentation for someone to use, not for its own sake. Who are you writing it for? How are they going to use it? What is their opinion on what makes quality documentation?

  • 2
    In less obvious terms, I think the OP is asking, "The consensus among software developers is to favor code clarity over additional documentation. Are operator overloads obtuse enough that additional documentation is favored over unavoidably less code clarity, and what would such documentation look like?" – Robert Harvey Jun 29 '16 at 22:10
  • @RobertHarvey: Based on the comments and other answers, I just realized that we may be talking past one another. I do not consider code comments "documentation". The audience of a comment is future developers working on modifying this code; the audience of documentation is users of this code. Those are very different audiences with different needs. Comments are written by developers; documentation is written by user educators. (Possibly same person, but different roles.) That said, I think my advice is good regardless of whether the "documentation" is user-facing or developer facing. – Eric Lippert Jun 29 '16 at 22:38
0

An hour of commenting your code saves a week for those trying to add a feature to an existing code. I haven't seen overly-documented code aside from textbook examples.

The thing is I don't know if I should document my overloaded operators, I mean, it is kind of obvious, isn't it?

It can be obvious. To the author. For a year. But think about newcomers that are going to add features to your code. It is not that obvious to them. They are unfamiliar with our style. They might not know some language features.


Here is a Java example: The style of old and new parts is notably different. For instance, older code uses anonymous inner classes, while newer code relies on lambdas. Feels like a mix of Latin and modern Italian.
Programmers with different skill levels and preferences have very different styles.
GUI labels are not hard-coded (which is good), but are stored in several places for historical reasons. So, you can't search a project for a label text.
Comments a minimal.

In this situation it takes several hours just to get to the class, dealing with an element that you want to modify.

  • 1
    If you can not read your code without adding comment, then re-factor the code to make it easier to read. There are two exceptions to this 1) comment why (not how or what). 2) comment where the programming language lacks expressiveness (assembler language programs will have a lot of comments). Note the name of variables and methods must be unique anything else about the choice of name is comments, this type of comment is good. Use good names. – ctrl-alt-delor Jun 29 '16 at 22:31
  • @richard In older projects it is getting tough. – sixtytrees Jun 29 '16 at 22:35
  • Are you saying that your code decays with age. This is common, but is not inevitable. With good coding practice, code can improve with age, and costs can be reduced. (see agilemanifesto.org ) – ctrl-alt-delor Jun 29 '16 at 22:38
  • @richard I have read about self healing code that gets better over time, but I haven't seen it in the wild. there are many things out there that I haven't seen. Glad if your team produces code that improves over time. – sixtytrees Jun 29 '16 at 22:44
  • 1
    I have worked in many teams. They were all split, with some believing that it could be done, and doing it, the others not believing that it could be done and not doing it. I do not know which way the causal relationship goes. I suspect it is a circle. I do knew that those that did not believe were good at excuses. I got a lot of “there is no such thing as 100% perfect code”, they did not try. Those that believed in 100% perfect code, produced 95 to 99% perfect code, or better. And what is more they did it cheaper. Writing perfect code is hard, but it is easier than fixing imperfect code. – ctrl-alt-delor Jun 29 '16 at 22:56

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.