Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 7 years ago.
Improve this question
Our team is moving into much larger projects in size, many of which use several open source projects within them.
Any advice or best practices to keep libraries and dependancies relatively modular and easily upgradable when new releases for them are out?
To put it another way, lets say you make a program that is a fork of an open source project. As both projects grow, what is the easiest way to maintain and share updates to the core?
Advice regarding what I'm asking only please...I don't need "well you should do this instead" or "why are you"..thanks.
With clones of open source projects one of your biggest headaches will be keeping in sync/patched according to the upstream sources. You might not care about new features, but you will sure need critical bug fixes applied.
My suggestion would be to carefully wrap such inner projects into shared libraries, so you can more or less painlessly upgrade just those parts if the ABI is not broken by the changes.
One more thing - if you find and fix bugs in an open source project - don't keep the fixes to yourself. Push the patches upstream. That will make the project better and will save you days of merging with a new version.
In order of preference
Make as few changes as possible to the third party libraries. Try and get around their limitations within your code. Document your changes and then submit a patch.
If you can't get around their limitations, submit your change as a patch (this may be idealistic with the glacial pace of some projects).
If you can't do either of those things, document what you've changed in a centralized location so that the poor person doing the integration for new versions can figure out what the heck you were doing, and if the changes made are still needed.
1 and 2 are greatly preferred (however, fast and very slow respectively), while the third option will only lead to headaches and bugs as your code base deviates from the dependencies' code base. In my code, I don't even have the 3rd party code loaded up in the IDE unless I have to peruse a header file. This removes temptation to change things that aren't mine.
As far as modularity, and this is assuming you are using relatively stable 3rd party libraries, only program to the public facing interface. Just because you have the source doesn't mean you have to use it all over your code. This should allow updates to be essentially drag and drop. Now, this is completely idealistic but its what I strive for with code I work on.
Related
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 1 year ago.
Improve this question
I'm working on a project that I want to publish on GitHub. This project requires a specific algorithm Algorithm. Every project I have worked on previously has only used my code (plus STL, etc.), but Algorithm can be a pain in the butt to write, so I want to use someone else's. Algorithm is a small subroutine compared to the size of the rest of my code.
I find a GitHub repository that implements Algorithm, but there is a lot of Junk. By Junk, I mean code I don't need. I want to strip away all the Junk from Algorithm and use it, but I'm not sure how to do that. Ideally, Algorithm could be cleaned off and placed seamlessly within my project directory to reduce dependencies for other users of my project.
I don't know the etiquette for using someone else's code. I don't know how to give credit or what the deal is with all these licenses.
It appears to me that I have five options for how to use someone else's implementation of Algorithm.
include the original header that declares Algorithm and all the Junk that comes with it. (Do I copy the header and all of its dependencies into my project directory?)
Create a new header and source file that keeps the implementation Algorithm as-is with all comments and #include the header into my project (leaving out additional functions and classes that may have appeared in the original header).
Modify the code implementing Algorithm to remove the remaining Junk. Remove comments. Change C arrays to std::vectors. Replace pointers with smart pointers. Change thrown exceptions. Remove "options" that my project doesn't need. Change the representation of data to merge everything with my project.
Rewrite Algorithm from scratch, but model it after the existing code, conforming the implementation to my style and making minor performance improvements (nothing that is worth pulling onto the existing repository, however).
What are the rules of etiquette for each of the 4 situations? Where do I put the Algorithm within the project directory? How do I credit someone else's work? How do I credit someone for their modified work (that, for example, removes their original comments)? How do I avoid crediting someone else for work I did (that they may think, hypothetically, uses bad coding practices)? What GitHub features facilitate all this?
Regarding licenses, if using someone's Algorithm to get my code running forces me to publish it with a specific license, can I later implement my own Algorithm and change the licencing? I don't know if I will care to do that, but it would be nice to know.
In general, when a developer releases code on Github under a specific license, they expect the code to be taken and used elsewhere in accordance to this license. There is no additional burden on you to appease the developer in any way except following the license.
MPL2 is very open to taking the code and incorporating it in another project even of a different license, as long as the licensed file itself (and any changes you make to it) stays licensed under MPL2. MIT license is even more permissive, here you can relicense as you see fit. Note that you still need to follow the attribution clause, citing MIT licence:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
So just keep this header intact. For MPL2 see the FAQ.
If you later choose to remove the code from your project and reimplement the same logic in a clean way, the copyrighted code is gone and so are the license terms.
Now to the best practices:
If you don't see a need for bigger changes in the code, and it doesn't come with lots of baggage, you would include it (mostly) untouched, which gives you the advantage of being able to upgrade the code easily later on. Expect the original implementation to move on, especially regarding bug fixes. Try to profit from them by staying close to the original instead of ending up with a bunch of code that you now have to maintain yourself.
If you have substantial, general improvements to the code in mind, e.g. modernization as you mentioned, consider to give them back in form of a pull request. For this, again, you need to keep the overall structure of the original code intact so the pull request will indeed only contain these improvements. The original author now may choose to benefit from your improvements or not. If they do, we get back to point 1: even while you did significant changes to the code, you can still profit from maintenance by the original author.
If there is a lot of junk involved that is unnecessary to your project and that you feel is a maintenance burden or comes with additional dependencies, or if your changes are both significant and specific to your own implementation so you don't see them being helpful to the original author (or generally see the chances of a successful pull request being slim) then just bite the bullet and fully assimilate the code. This is also the best option when the original project appears 'dead', e.g. no significant commit activity in ages etc.
Obviously there is no general rule as of what option is best so this is supposed to merely guide you with the decision.
Note that there is also a technical consideration of "how" to adopt the code. It may be beneficial for you to maintain a clean copy of the code (as in, self-contained and not part of your bigger project) with your changes in a separate repository which you explicitely forked from the original repository ("upstream") on Github (but you can also do it privately with git itself). This gives you the advantage of git's features regarding keeping track of changes and merging them between upstream and your fork. The source used by your bigger project is your own forked repository, which you may or may not keep in sync with upstream. This fork is also a starting point for any pull requests you may have in mind for upstream.
When you fork a repository on GitHub, the original author is able to see your fork and therefore that their work is being used. Also if you find and file bugs or suggest improvements you are giving positive feedback to the author. Finally, a pull request is the crown jewel of showing your appreciation. But as a developer who publishes stuff on GitHub, it is never my expectation to receive any of it.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 9 years ago.
Improve this question
I'm having a read of other people's source code from open source projects such as Pidgin, Filezilla and various others so that I may get a brief idea how software really is written.
I noticed that when writing GUI, they like to split the whole interface into classes.
More or less, lots of projects I see every single bit broken down, into perhaps a total of 70 files (35cpp and 35.h).
For example: 1 listview may be an entire class, a menubar may be a class or a tabview a whole module.
And this isn't just the UI part - the network modules are also broken down by a huge amount - almost every function itself is a .cpp file.
My question: Is this really just preference or does it have any particular benefit?
I for example would've written the whole UI into a single module..
What is the actual reason?
Some languages encourage one file per type, and people who know those languages also program in c++, and bring that habit here.
For reuse, you want thing you put into a header to be simple, orthogonal, and conceptually clean, this tends to mean avoiding files that have everything one particular project needs.
Before git/mercurial it could be a real hassle to have multiple people edit the same file. Thus separating things into lots of files help a lot with multiple people editting, both for the edits and for your version control software.
It also speed up compilation. The small the file you are editting, the less compilation is needed, so unless the linking stage is slow, small file is a very good thing.
Many people have been hurt by cramming things into a single or small numbers of files. Few people have been seriously hurt by chopping them up into 50+ files. People tend towards things that dont overtly teach you hard lessons.
you might want to split the project into separate files to improve readability and to sometimes also make debugging easier. The filezilla project could have all been written into just two files something like main.cpp and main.h but if you do that, you will have to write tens of thousands of codes into the same file which is a very bad programming practice even though it is legal.
One benefit will come from Testing. Distributing system testing throughout the design hierarchy (e.g. rather than a single physical component) can be much effective and cheaper than testing at only the highest-level interface.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 3 years ago.
Improve this question
We are aiming to leverage software reuse in embedded ARM/Linux platforms. Some of our hardware platforms are designed for customers' specific needs. Of course the application would be customized in various ways too.
While it is not an Android product, for one it is way too big compared to ours, it does make a good analogy in that other than the constant of being Linux based, there are different look and feel to the UI, there are different phones, there are different CPUs, there are different firmwares for different radios, etc. So there are many configurations to manage. And the configurations are a sparse matrix, in that not all combinations exist.
Continuous Integration is also not completely out of the picture in the future.
So for the near future the end point seems to be:
A core set of libraries that we want to keep developing and apply everywhere. Class inheritance supplies the customizations. So there is a build configuration for the application types.
A handful of customized ARM/Linux hardware platforms. Seems a BSP/board class HAL for our libraries is the way to go. That means a build configuration to pick the right hardware/board.
A handful of co-processor firmwares matching to the hardware/board, but the API to our libraries is the same. So there is a build configuration depending on the firmwares.
A handful of implementation for different look and feel/applications. That's another build configuration.
Needless to say there are many include paths, #define's, and file exclusions to make all these work.
So as you can see, if we wanted a collection of Eclipse/CDT projects in a workspace that allows us to build all these variants in the same environment all at once, there are a lot of configurations to create and manage in Eclipse/CDT. If the GUI is the only way to manage, there is a whole deal of mouse clicking to do. And after that there is no simple way to verify that all configurations are setup correctly without a whole lot more mouse clicking. There isn't a dashboard view. Is there a text editor based approach to manage all these?
I did try to do my homework. I understand that there is the 'Import Settings...' and 'Export Settings...' buttons in the 'Paths and Symbols' tab. But it does one configuration at a time, for one project at a time. It doesn't seem very systematic and is easy to miss something.
I have also look directly at .cprojects but I worry that if I made a mistake Eclipse will just silently do the unexpected things and will take big effort to fix.
Do fellow experts have a better suggestion?
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 3 years ago.
Improve this question
I just stumbled upon Adobe source libraries, ASL. It is set of templates and functions similar to boost, under MIT license.
Some of the utilities in the library I found quite useful and now I consider using it.
the library seems pretty straightforward, however.
Have you used ASL yourself? if so, what were your impressions? do you recommend it?
does it work well with a range of compilers and platforms e.g. IBM C++, ICC, g++?
have you encountered quirks/unexpected things?
thanks
ASL uses Boost heavily, so it's not such similar to Boost, as (in some cases) a relatively thin wrapper around Boost.
The "big" pieces of ASL are Adam and Eve. Most of the rest appears to be (and if memory serves, really is) little more than support for those.
ASL hasn't been updated in a while, and if I'm not mistaken some of what it provides in wrappers around Boost has now been incorporated into the Boost libraries themselves (most Boost authors have been aware of ASL at least since they featured in Sean Parent's keynote presentation at Boostcon 1).
My own experience with them has been somewhat mixed. At one time, I used a couple of their Boost-wrapper classes a bit, but IIRC, within the next release or two, the bits I cared about were available in Boost without any wrappers (though offhand, I don't remember exactly what those pieces were...)
Adam and Eve are kind of cool for playing around with different UI layouts and such -- but I've never used them for a finished version of a program. At least to me, it appears that they're useful primarily with a relatively complex UI. My impression was that if you find them very useful, your UI probably needs work. If you need Adam and Eve to help understand what's going on, chances are your users can't figure out either.
OTOH, there are probably at least a few cases where a dialog is clear to a user, but the code much less so to a developer. If you do a lot of disabling some controls until values have been entered in other controls, and such, it can make it a lot easier to ensure controls are disabled until all values they depend upon have been entered.
As already noted, thew whole point of ASL is Adam and Eve, the rest are just handy tools.
Adam & Eve work together to describe UI with auto-layout in a cross-platform way.
If this is not what you need, then you should probably not spend much time on ASL.
Eve has the typical collection of vertical/horizontal/other containers for auto-layout.
And scripting with Adam allows you to achieve things difficult (if not impossible) to achieve just with layout containers (things like keeping separate groups of controls the same size, for instance).
True, you implement some of the rules in your C++ code. But it makes sense to store the UI description rules related to UI behavior in the same place where you store the UI to begin with.
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
I'm working on a fairly big open source RTS game engine (Spring). I recently added a bunch of new C++ functions callable by Lua, and am wondering how to best document them, and at the same time also stimulate people to write/update documentation for a lot of existing Lua call-outs.
So I figured it may be nice if I could write the documentation initially as doxygen comments near the C++ functions - this is easy because the function body obviously defines exactly what the function does. However, I would like the documentation to be improved by game developers using the engine, who generally have little understanding of git (the VCS we use) or C++.
Hence, it would be ideal if there was a way to automatically generate apidocs from the C++ file, but also to have a wiki-like web interface to allow a much wider audience to update the comments, add examples, etc.
So I'm wondering, does there exist a web tool which integrates doxygen style formatting, wiki-like editing for those comments (preferably without allowing editing any other parts of the source file) and git? (to commit the comments changed through the web interface to a special branch)
We developers could then merge this branch every now and then to add the improvements to the master branch, and at the same time any improvements by developers to the documentation would end up on this web tool with just a merge of the master branch into this special branch.
I haven't found anything yet, doubt something this specific exists yet, so any suggestions are welcome!
This is a very cool idea indeed, and a couple of years ago I also had a very strong need for something like that. Unfortunately, at least back then, I wasn't able to find something like that. Doing a quick search on sourceforge and freshmeat also doesn't bring up anything related today.
But I agree that such a wiki frontend to user-contributed documentation would be very useful, I know for a fact that something like this was recently being discussed also within the Lua community (see this).
So, maybe we can determine the requirements in order to come up with a basic working draft/prototype?
Hopefully, this would get us going to initiate such a project with a minimum set of features and then simply release it into the wild as an open source project (e.g. on sourceforge), so that other users can contribute to it.
Ideally, one could use unified patches to apply changes that were contributed in such a fashion. Also, it would probably make sense to restrict modifications only to adding/editing comments, instead of allowing arbitrary modifications of text, this could probably be implemented by using a simple regex.
Maybe, one could implement something like that by modifying an existing (established) wiki software such as mediawiki. Or preferably something that's already using git as a backend for storage purposes. Then, one would mainly need to cater for those Doxygen-style comments, and provide a simple interface on top of it.
Thinking about it some more, DoxyGen itself already provides support for generating HTML documentation, so from that perspective it might actually be interesting to see, how DoxyGen could possibly be extended, so that it is well integrated with such a scripted backend that allows for easy customization of embedded source code documentation.
This would probably mainly boil down to providing a standalone script with doxygen (e.g. in python, php or perl) and then optionally embed forms in the automatically created HTML documentation, so that documentation fixes/augmentations can be sent to the corresponding script via a browser, which in turn would write any modifications back to a corresponding branch.
In the long term, it would be cool if such a script would support different types of backends (CVS, SVN or git), or at least be implemented generically enough, so that it is easily extendible.
So, if we can come up with a good design, it might even be possible that such a modification would be generally accepted as a contribution to doxygen itself, which would also give the whole thing much more exposure and momentum.
Even if the idea doesn't directly materialize into a real project, it would be interesting to see how many other users actually like the idea, so that it could possibly be mentioned in the doxygen issue tracker (https://github.com/doxygen/doxygen/issues/new).
EDIT: You may also want to check out this article titled "Documentation, Git and MediaWiki".