How can I understand the architecture of an existing code-base?
October 17, 2016 1:10 PM Subscribe
Help me to make sense of this largish C++ repository, so I can become an upstanding citizen and contribute to the program and give back to the community.
As a hobby project, I started playing around with the Raspberry Pi and arcade emulation. The software written for it is wonderful, and free to boot! The front-end presenting the games to the user (not only me, but also my kids) is good-looking, but really not very kid-friendly. All configuration menus out in the open, and no file-filtering whatsoever.
So about 1.5 year ago, I made the plunge and forked the front-end (EmulationStation) on Github, hacked some initial shielding of the most sensitive features, and added a way to filter games.
The reception of this new fork was quite good, apparently this fills a need, and I've been happily puttering along in the code, adding this thing and that.
And then came the issues.
Of course there are a lot of requests that are outside my scope, which I have no intention to adress. Other issues currently logged are genuine bugs though, and I feel responsible to fix them. This is where things started to fall apart.
Solving and subsequent testing for one thing lead to finding other bugs, and now I am about five months in. I have have several partial re-designs partly implemented and I feel completely lost. On top of that, I feel the code actually is in worse shape then I started. Now, because of git, I should be able to revert to a more stable situation, but that still does not solve the issues at hand.
While I code for work, I have no formal CS background, and its starting to show. I have trouble getting a good grip on the totality of the project, and to see how modules come together (and are going wrong). I have the feeling that my problem lie in the realm of me using ugly code hacks/patterns, and the subsequent lack of maintainability combined with an overall lack of design strategy/architecture. So how do I improve?
Things I've tried:
*Re-Starting from scratch, the second implementation was different, but not necessarily any more stable.
*Visualize the code networks using doxygen, that was fun, but not really enlightening.
Practical constraints:
*The program is written in C++, roughly 75K LoC.
*The original developer has communicated he no longer has time/interest to work on the code.
*The program itself is platform agnostic in principle, but I only ever got it to compile on the R-Pi itself. This makes my workflow: Code in an IDE on windows (Netbeans or Visual Studio) > copy to Pi > compile & drink coffee > make sense of debug messages dumped to console > refine code.
So finally, the questions:
How should I start to make sense of this project?
Can you recommend books on SW architecture, maybe in a C++ context?
Does it make sense to put out a consultancy contract to get a couple of coaching sessions or feedback from someone with a higher level of experience than me?
As a hobby project, I started playing around with the Raspberry Pi and arcade emulation. The software written for it is wonderful, and free to boot! The front-end presenting the games to the user (not only me, but also my kids) is good-looking, but really not very kid-friendly. All configuration menus out in the open, and no file-filtering whatsoever.
So about 1.5 year ago, I made the plunge and forked the front-end (EmulationStation) on Github, hacked some initial shielding of the most sensitive features, and added a way to filter games.
The reception of this new fork was quite good, apparently this fills a need, and I've been happily puttering along in the code, adding this thing and that.
And then came the issues.
Of course there are a lot of requests that are outside my scope, which I have no intention to adress. Other issues currently logged are genuine bugs though, and I feel responsible to fix them. This is where things started to fall apart.
Solving and subsequent testing for one thing lead to finding other bugs, and now I am about five months in. I have have several partial re-designs partly implemented and I feel completely lost. On top of that, I feel the code actually is in worse shape then I started. Now, because of git, I should be able to revert to a more stable situation, but that still does not solve the issues at hand.
While I code for work, I have no formal CS background, and its starting to show. I have trouble getting a good grip on the totality of the project, and to see how modules come together (and are going wrong). I have the feeling that my problem lie in the realm of me using ugly code hacks/patterns, and the subsequent lack of maintainability combined with an overall lack of design strategy/architecture. So how do I improve?
Things I've tried:
*Re-Starting from scratch, the second implementation was different, but not necessarily any more stable.
*Visualize the code networks using doxygen, that was fun, but not really enlightening.
Practical constraints:
*The program is written in C++, roughly 75K LoC.
*The original developer has communicated he no longer has time/interest to work on the code.
*The program itself is platform agnostic in principle, but I only ever got it to compile on the R-Pi itself. This makes my workflow: Code in an IDE on windows (Netbeans or Visual Studio) > copy to Pi > compile & drink coffee > make sense of debug messages dumped to console > refine code.
So finally, the questions:
How should I start to make sense of this project?
Can you recommend books on SW architecture, maybe in a C++ context?
Does it make sense to put out a consultancy contract to get a couple of coaching sessions or feedback from someone with a higher level of experience than me?
Best answer: I can't help with the specifics of C++, but TheAdamist's advice to get it building on a desktop is good. Anything that speeds up your change/rebuild/check cycle is important, and if I was doing this, then it would be the first thing I would focus on.
Michael Feather's book "Working Effectively with Legacy Code" is good for advice on working with a big existing project. His advice is broadly "refactor it, and add tests" - but he has more specific advice on how to do that. While I was checking the details of the book, I also stumbled across this Stack Exchange answer on a similar topic, that has good advice.
posted by siskin at 2:19 PM on October 17, 2016 [1 favorite]
Michael Feather's book "Working Effectively with Legacy Code" is good for advice on working with a big existing project. His advice is broadly "refactor it, and add tests" - but he has more specific advice on how to do that. While I was checking the details of the book, I also stumbled across this Stack Exchange answer on a similar topic, that has good advice.
posted by siskin at 2:19 PM on October 17, 2016 [1 favorite]
Is there any way you can talk to someone who's been working on the project for awhile? Is there a mailing list or slack or contact through the repo? It sounds like you're kind of on your own. A good way to grow exponentially as a new/inexperienced programmer is to start talking to people and asking them your "dumb" questions.
posted by stoneandstar at 4:48 PM on October 17, 2016
posted by stoneandstar at 4:48 PM on October 17, 2016
Best answer: Following stoneandstar, coding alone can be really tough, find or build up some community if only to vent. Your code is probably much better than it seems, sound like it compiles! Faster and easier compile times and tools are worth it but if this is tied to hardware automating testing which is often a key suggestion could be a lot of work.
Have you made a block diagram of the core elements? Some rough sketches could help refer back where things connect.
another tool
Hard to agree with a consultant, anyone good enough will probably be quite expensive and it'd take more time than would ever be reasonable for a non-corporate project.
Add the github project here, perhaps someone can take a peek.
It really sounds like you're doing great, frustration (stairwell time;-) is part of many projects. Keeping at it steady for months and making releases is really most commendable!
posted by sammyo at 5:35 PM on October 17, 2016
Have you made a block diagram of the core elements? Some rough sketches could help refer back where things connect.
another tool
Hard to agree with a consultant, anyone good enough will probably be quite expensive and it'd take more time than would ever be reasonable for a non-corporate project.
Add the github project here, perhaps someone can take a peek.
It really sounds like you're doing great, frustration (stairwell time;-) is part of many projects. Keeping at it steady for months and making releases is really most commendable!
posted by sammyo at 5:35 PM on October 17, 2016
Best answer: I highly recommend the (nice, short) book A Tour of C++ to get up to speed on all the modern features of C++, with guidance on how and when to use them. You may need to upgrade your toolchain if your compiler doesn't support C++11.
In addition to the Feathers book already recommended, which is excellent, I'd pick up UML Distilled, which is also a nice short and extremely practical handbook. I like to draw out the basic class structure by hand as I walk through code to get a sense of it. Then if I want to share it with others I'll draw it up with Eclipse Papyrus UML editor.
posted by Joe Chip at 8:12 PM on October 17, 2016
In addition to the Feathers book already recommended, which is excellent, I'd pick up UML Distilled, which is also a nice short and extremely practical handbook. I like to draw out the basic class structure by hand as I walk through code to get a sense of it. Then if I want to share it with others I'll draw it up with Eclipse Papyrus UML editor.
posted by Joe Chip at 8:12 PM on October 17, 2016
Best answer: One way to approach this is to start writing unit tests for this code. When you come to a mass of code that is very difficult to write unit tests for, start breaking it up and writing unit tests for each new part, then connect those parts back up. By doing that, you may understand how those parts work and fit together and have – in the tests – a written contract that explains how they work. Alternatively, you may discover that you didn't need to break it up, which will give you insight, too.
posted by ignignokt at 7:02 PM on October 18, 2016
posted by ignignokt at 7:02 PM on October 18, 2016
Response by poster: Hey thanks for the excellent suggestions. You've given me a lot to think about, and plenty of handles to try and get a grip on this.
I'll be starting with the UML based sketching of the main layout.
Second on my list is a selection of the recommended literature.
Writing unit tests would be a novel thing for me, but in that sense it is a worthwhile learning experience, I think.
For those interested in the repo in question, here's my fork.
posted by Zigurana at 1:56 AM on October 19, 2016
I'll be starting with the UML based sketching of the main layout.
Second on my list is a selection of the recommended literature.
Writing unit tests would be a novel thing for me, but in that sense it is a worthwhile learning experience, I think.
For those interested in the repo in question, here's my fork.
posted by Zigurana at 1:56 AM on October 19, 2016
« Older No Sound in Media Encoder-Rendered files? | How wasteful is a meal delivery service? Newer »
This thread is closed to new comments.
There will be a main entry point in the code. parse arguments, init things, and then kickoff a main loop somewhere that actually does the emulation. Understanding the main control flow would be a good start.
Do the doxygen code networks help give you a sense of how modular things are? If it has any sense of modularity, figuring out how the modules work together is a good step. If its a mess, can you figure out how to make it modular?
Is there duplicated code everywhere that you can consolidate?
Good programming form seems to come with experience, i'm not aware of a good way of learning it.
posted by TheAdamist at 1:38 PM on October 17, 2016