Tag Info

Hot answers tagged

130

This is awesome. I wish more software developers took the time and effort to do this. It: States in plain English what the class does (i.e. it's responsibility), Provides useful supplementary information about the code without repeating verbatim what the code already says, Outlines some of the design decisions and why they were made, and Highlights some ...


34

The key to working with a large codebase is not having to read the entire codebase to make a change. To enable a programmer to quickly find the code he is looking for, code should be organized, and the organization apparent. That is, each logical unit in the code, from the executable, the library, the namespace, down to the individual class should have a ...


26

Contrary to other answers, I would say no. The code should be self-documented as much as possible. Such simple things should not need to be explained in the code. I do not know SAP, but a simple google query pointed to the SAP reference page to the line_exists function. If the maintainers and developers are not up to date, then the company needs to develop ...


19

In the context of ABAP you can rarely expect everyone to be familiar with all the newest features because: ABAP has such a long history and the ancient language constructs are still encountered all the time (I am currently modifying a report which uses a logical database and makes excessive use of tables with header lines). SAP themselves rarely uses the ...


14

I would not agree this is a very good approach, mainly due to When you refactor your project, move methods around, the documentation breaks. If documentation is not properly updated, it will result in more confusion than help understanding the code. If you have unit tests for each method/ integration tests for each module, it would be a self ...


8

I think it depends on the situation. In this example, documentation like this belongs in a README file.* If you consistently use the new syntax, your code will be virtually unrecognizable to a programmer who only knows the older style. Your maintainers will thank you if you warn them up front that they don't actually know this language. I would: Start ...


8

This might not answer your question - depending on how much of a 'requirement' it is to have these examples in your documentation. Perhaps you could do a different angle: Provide examples in your JUnit tests. (Perhaps even a package like com.examples) The problem with code in comments is that your IDE is going to ignore it, for the most part. But your ...


7

In this case, someone unfamiliar with the updates could simply look up line_exists and move along. For something less searchable, you might want to leave a comment which simply names the new features you are using so that up-to-date documentation is easier to find. If you use these features in more than a few places, put such a notice in a readme file ...


6

I'm personally a fan of a high-level design document - preferably written BEFORE any code - that gives an overview of the design and a list of classes and resources. A top-down design greatly simplifies things - yours might be "game engine -> hardware -> controllers -> joystick"; thus, a new programmer told "fix the 'a' button on the 'xyz controller" would ...


4

The most important rule I have found for making it easier for new developers to understand a codebase is perfect agreement is expensive. If new developers must perfectly understand the system they are working on, it prevents all opportunities for on the job learning. I think the programmer's notes are an excellent start, but I would go further. Try to ...


3

I have seen large classes with documentation, and after reading the documentation I haven't got a clue what this class is supposed to be good for and why anyone would use it! And at the same time, I had a need for some functionality and I was absolutely sure there must be a class to handle it, and couldn't find it anywhere - because there was no ...


3

Note: I am not very familiar with ABAP, so I am answering as if someone asked about using lambdas in Java, in the understanding that the issue is similar (AFAIK it is). If I am wrong, please inform me. This does not belong to comments (part of the code) as it is an specification issue of the project. In fact, it should not be a programmer who decides to use ...


2

If the code base is large - I try to provide a design document that maps out the key elements of its design and the implementation. The intention here is not to detail any of the classes used, but provide a key to code and the thought that went into the design. It gives a overarching context to the system, its components and the application thereof. Things ...


1

In one respect I think this is a bit of an X-Y problem. For the sake of my example I'd like anyone reading this to consider C++'s recent C++11 overhaul. In particular I would like to focus on the constexpr operator. It's purpose is to allow certain functions to be run by the compiler (e.g. a factorial function) at compile time, thus preventing constant ...



Only top voted, non community-wiki answers of a minimum length are eligible