ROSE Compiler Framework/Lessons Learned

Here we collect things to do due to some past lessons.

Do Not Format/Indent other people's code

Lesson:

A developer tried to understand a staff member's source code. But he found that the code's indentation was not right for him. So he re-formatted the source files and committed the changes. Later, the staff member found that his code was changed too much and he could not read it anymore.
Even worse, people will have difficulties in merging changes mixed with indentation changes and real changes.

Solution:

Please don't reformat code you do not own or will not maintain.

Physical locations matter

Lesson

we had a student who was assigned a desk which was in a deep corner of a big room. The desk was also far away from other interns. As a result, that student had less interactions with others. He had to solve problems with less help.

Solution:

Locations MATTER! Sit closer to people you should interact often. Make your desk/office accessible to others. Physically isolated office/desk may have very negative impact on your productivity.

Choose your development platform carefully

Lesson

Somehow new inters were assigned Mac OS X machines by default. But some of them may not be familiar with Apple machines or even dislike Mac OS X's user interface, including keyboard, window system, etc (a love-hate thing for Apple products). So they felt stuck with an uncomfortable development platform. We had interns who could not type smoothly on Mac keyboard even after one month. This is unnecessary.

Solution

Provide choice up front: Linux or Mac OS X. Reminder people that they have freedom to choose the platform they personally enjoy.

Use different git repositories for different tasks

Lesson:

A developer used different branches of the same git repository to do different tasks: fixing bugs, adding a new feature, and documenting something. Later on he found that he could not commit and push the work for one task since the changes for other tasks are not ready.

Solution:

using separated git repositories for different tasks. So the status of one task won't interfere with the progress of other tasks.

Introducing software dependencies very carefully

Lesson

ROSE did not depend on boost C++ library in the beginning. But later on, some developers saw the benefits of Boost and advocated for it. Eventually, Boost becomes the required software to use ROSE.
But Boost library has its disadvantages: hard to install (just see how many boost issues on our public mailing list), lack of backward compatibility (codes using older version of boost break on new versions), huge header files with complex C++ templates slowing down compilation or even breaking some compilers.
We still have internal debates about what to do with Boost. It is often a painful and emotional process.

Solution:

Introducing big software dependency very carefully. Or you will get stuck easily.
At least ask people who advocate for new software dependency to be responsible for maintaining it for 5 years and providing an option to turn it off at the same time.

Create Exacting Tests Early and Often

Lesson:

A developer created tests that were too broad, mostly because they were included late in development. This led to passes that should not have passed, that is passing all tests even though the code had been broken.

Solution:

Make sure that tests check results carefully. This is made much easier by making sure your functions have precisely ONE intention. E.g. if you need to transform data and operate on the transformed data, split the transformation and the operation into two functions (at least).

Keep Code Readable While Coding

Lesson:

A developer wrote code without commenting initially, then came back to the code and had to go through the arduous task of understanding

his own unreadable code.

Solution:

Keep variable and function names meaningful. Do full documentation as you go, do not leave it for later.

Think Before You Code

Lesson:

A developer wrote code without minding the structure. This led to bloated and unreadable code that would have to be

refactored several times.

Solution:

A programmer must code AND design, not just code. Well structured code is much easier to read then badly structured code

Remember The User

Lesson: A developer wrote the code without knowing what the users actually needed. This led to serious refactoring that could have been avoided, or at least made simpler, if he had concentrated on the user at all times.

Solution: Whenever possible ask users for their input. It will save you a lot of trouble in the long run.

The User is Paramount

Lesson: A developer wrote a rather obtuse component without understanding exactly what the user might want this for

Solution: At the very least check that the input and output are what the user wanted, this will save much time and aggravation

references

http://www.projectsmart.co.uk/lessons-learned.html