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
My question is in regard to referencing open source frameworks. There are many of them for many different purposes. I personally leverage several of them in a single project. For example:
Unity
CAL/Prism
ValidationAspects
EnterpriseLibrary Logging
EnterpriseLibrary Exception Handling
EnterpriseLibrary Caching
Caliburn
All of these frameworks have helped greatly from a development effort perspective. There are however some negative aspects involved:
Tons of dlls (15 from the above list).
Application level (non-common assemblies and new assemblies) must reference many core dlls, which can be confusing) and tons of different namespaces are involved.
Deployment of said tons of dlls can get problematic (I sometimes use ILMerge to alleviate this and the above problems, but let's put that aside for now).
Open source project lifetime - open source projects come and go, so if any of these become no longer actively maintained, it can be concerning if there are internal bugs that need fixing or enhancements we want.
Obfuscation of "how to do things". We don't actively leverage every part of the above frameworks. In fact, several of these frameworks have overlap and provide redundant components and functionality. In terms of development, this can be confusing. We want a consistent implementation that is straightforward and easy to understand across our code base. Having multiple areas that do the same thing in different ways can be troublesome in this respect. This is probably one of my biggest concerns.
You're in big trouble if these frameworks reference different versions of other assemblies (ie. one internally references Unity 1.1 and another Unity 2.0).
The alternative? Include the source code in a common dll for your project(s) (ie. MyProject.Common). Let's put aside the issue of adherence to license requirements for the time being.
This has several negative implications too:
It's not as easy to leverage updates released by the framework's provider - you need to update your source code.
Encapsulation of functionality - it's easier to break this paradigm when the source code is all in your hands.
So, I know people probably have lots of opinions on this...and I'd like to hear them.
Thanks.
For some aspects of your problem, this might be relevant: http://en.wikipedia.org/wiki/DLL_hell#Running_Conflicting_DLLs_Simultaneously.
Another common solution to this problem is to write an encapsulation layer on top of the functionality needed, which at least protects your code from wild changes when upgrading to new versions of supporting libraries.
As to open source project lifetime, it should be clear which projects are healthy and which are not. For example, a project that is part of the Apache or Eclipse foundations are probably healthy, whereas some random thing on sourceforge is probably not. Generally, you can avoid this problem altogether by avoiding projects that do not seem active.
For the negatives to copying code into your project:
I know you wanted to put license aside, but you cannot in reality. I am not a lawyer and you should consult with one for your project if there may be issues, but if you are developing a proprietary system it could become GPL'ed accidentally.
It makes your development environment more cluttered. You have to worry about making sure the copied-in code ompiles properly, is being compiled with the right version, and has the right build scripts. You also have all this extra code in your IDE that takes up space.
As you pointed out, it makes updating code very difficult.
If you have to file bugs with the Open Source project, it becomes more difficult to do.
If you're not careful, a junior developer who doesn't know any better could go into the code and start mucking around with it.
There's probably more reasons not to do it, but that's a few. Hope that helps.
Related
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
I've been holding off on releasing a library I wrote because it is the first library which I'll be releasing publicly. Here are my concerns:
The library isn't complete it is in a very usable state, I'd say it is version 0.3, however it still lacks a number of features which I would like to at some point implement, and control how they're implemented (meaning not merging someones implementation).
I'm fearful of criticism, I know there are a few things which should be reorganized/refactored, but I wrote the initial class quickly to be functional for another project I am working on.
So when is the best time to release? Should I just throw it up on github and work on the issues post-release? Or should I wait until I refactor and feel completely comfortable with what I have written?
Most classes/libraries I see are always very elegantly written, however I have not seen any in very early release stages, are a lot of classes fairly sloppy upon initial release?
Release early, release often.
Criticism is a good thing as long as its constructive. Ignore the haters, pay attention to the folks filing bug reports and commenting.
The internal structure of the code matters, but it matters more if it works for its intended purpose. In general, refactoring will change how code works internally but will not affect how it is used. Same inputs and outputs.
You need to get something half-way
useful first, and then others will say
"hey, that almost works for me", and
they'll get involved in the project.
Linus Torvalds
Linux Times (2004-10-25).
It depends on why you are doing this. If it's to provide something useful and it's useful and has benefits that no other library has, then go for it. Just list the status and what's coming next.
If you are doing this to point to on a resume, get it in good shape (the code, not necessarily feature complete). Imagine a future employer poking around the code to see what it looks like, not downloading and running the code.
Whether you release the code in an incomplete state or not, it's always worthwhile having enough documentation to allow users to understand how to use the library.... even if it's only API docs. Make sure that anything incomplete is tagged as TO DO - it helps to maintain a target list of tasks to complete, and lets users know that the feature/method/whatever hasn't been forgotten.
Providing a set of code style/standard documents (perhaps with architectural notes on class relationships) allows other developers to contribute more readily, and in a manner that enhances the library rather than making it a hotch-potch of spaghetti code. It's never easy releasing a library, then having to refactor, while maintaining backward compatibility for users who have already taken up and are using that library in a production setting.
EDIT
Don't be afraid of criticism... it goes with the territory.
Some critcism can be constructive (take heed of that).
There'll be plenty of other people who criticise your code (for whatever their reason) without being constructive, or who just denegrate your work. The difference is, you've produced the goods, they probably haven't ever contributed to any OS product/library.
Users expect you to fix their problems immediately, or to write their code for them to use your library, or simply say "it doesn't work" without any explanation of what they mean. You have to learn to live with that 24x7x365.
But just once in a while, somebody will thank you for saving them hours of work, or for providing something useful... and suddenly all the stress and hassle feels worthwhile.
I read a document by Joshua Bloch, a pricipal software engineer at Google that talked a lot about the best type of API design. Basically, once you release it, it is more or less set. He says
Public APIs are forever - one chance to get it right
You can check out the slides here. It's definitely worth reading. I have a PDF of it as well; let me know if you need 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 5 years ago.
Improve this question
I need to document a MS-Access application that was created, developed and maintained completely by a power-user over 10 years.
This is an interesting situation because what they want is a manual so that a future developer can come in without prior domain knowledge and make changes to the frontend or the backend in a timely manner.
There are a few questions on my mind for this little project:
What is a good manual design creating application? Microsoft Word doesn't quite cut it.
What kind of things would you, the developer, need to know in order to make changes to things like forms, reports, tables or other Access objects?
Anything else I missed? Any pitfalls?
You could start with generating some automatic code documentation using MZ-Tools add-in for VBA. The same add-in can help you clean unused variable declarations, generate line numbers, reorder procedures within a module, etc.
Documenting forms is more difficult. My proposal would be to keep a screen shot, alltogether with a .txt file obtained through the undocumented application.saveAstext method.
In my experience, Access and VB6- based programs are plagued by more code replication and technical debt than programs in mainstream languages. I'm not sure why. Maybe it's the nature of Access as a "prototype" or "toy" database (though it can be quite powerful when yielded correctly).
If I had to choose between expending time on documentation and expending time on reducing technical debt, for example by remodularizing, eliminating repeated code, splitting long functions, etc., I would choose the latter. The improvement to maintainability and readability would be greater.
I know this is closed for long, but I can't refrain adding my 2 cents:
In the case mentionned, I think the most usefull doc to produce is a FUNCTIONAL documentation (which should have existed before starting the development in an ideal world).
Second is within the code itself, and that includes the VBA but also the field descriptions which can be set in Access and SQL Server.
Third is a (or a set of) nice database diagram.
Once you have that, all the rest can be generated by the new developer using HIS favorite tools.
Speaking about tools, I particularly like and recommend:
MZ Tools: specially to easily find which routines call the one your looking at
Smart Indent: to properly indent code. Trying to read badly indented code makes me sick
SqlSpec: (not free) generates HTML doc of the database itself for most database engines
Have you tried the using the built in database documenter? It will print out all tables, indexes, forms, controls, each property of controls. Code, the sql used and just about any thing else. This results in huge, but just massive printouts. However, while it will kill a few trees in the process it sure is a great way to impress the boss.
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 8 years ago.
Improve this question
I have recently started working on some open source project which I found relevant to my interests.
During this initiation period I came across some terminologies/stuff that I am not acquainted with, like configure, tool chain, binutils, etc. which I agree depends upon the type of project you are working on.
Now my question is, are there some bare requirements a developer should know before starting to work on the project?
Any help/reference will be greatly appreciated.
EDIT:
I have seen the GNU configure and build system in most of the projects I have seen.
If someone bothers about it "The GNU configure and build system" is a good place to start.
If it's a pre-existing one, you'll need to read their development docs (if any), learn how to use their version control system, and have the requisite tools for building the code and running it.
If you have all that, and the knowledge of the code/language, then you just need enthusiasm and some spare time :)
I wouldn't define them as bare requirements in the sense that it appears you are looking for. If you're a programmer you already have (hopefully!) the self-learning and problem solving characteristics that probably led you to be a programmer at first.
You'll never really know 'everything', and will likely learn something new everywhere you go. Heck, I got my current job never even hearing the words "Model-View-Controller", but picked up the concept in no time.
Your examples, toolchain and binutils, are not complex concepts and a simple wiki article should suffice.
I'd suggest downloading all the source code and making sure you can build it yourself as a first step.
Try and make sure you are familiar with the overall design and documentation before attempting to make any changes to ensure you don't inadvertently break anything on your first change!
The terminologies being used will probably depend on the technologies being used, for example an open source project written in C++ and running on Linux, will likely be very different to a C#/.NET application build to run on Windows.
It depends on how much involvement you will get into. If you just want to contribute with a feature, just get the tools to build the project, an editor to change the file and enough doc reading to find injection point for your feature. If you can find someone to help you getting started it will be fairly easy.
If you are to be committed to the project I recommend learning build tools, project history and aims. Also how the current authors try to solve the problems, their perspective on the project will help.
I would say being able to understand all of the architecture, tools and technology for whatever project you're working on is a must.
However, you then tried to make this a generic question that applied to any open source project. You kind of answered that for yourself didn't you?
which I agree depends upon the type of
project you are working on
I would think that depends entirely upon the project. Most well set up software projects will specify:
What language(s) they're written in
What developer environments (if any) they're set up for
What tools you need to build/compile/run the project
Test data with which to test the software
What are you working on? Are you sure they don't provide any of this information?
It depends on what you qualify as "work" on the project.
Most of the answers here suggest that you're coding (and your question hinted in that direction), but there are things that you can do to contribute to projects -- like testing and documentation -- that can be done without knowledge of how the program's written.
Now, for the coding aspect of it -- if it's a smaller project, I'd try to figure out what the other contributor's motivation and grand plans/goals for the project are. As with any team, coming in and trying to take things in a completely different direction than the others are planning, even if you have good intentions, can cause all sorts of problems.
(and then there's the technical advice that everyone else said ... source control, build system, project architecture, toolkits used, etc.)
It depends, as you say, on the project.
You'll have to know how to work in the language, you'll have to be familiar with the source code control system they use (usually subversion). You'll have to be able to build (usually Ant, often Maven).
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 4 years ago.
Improve this question
After every new program written a lot of paper documentation remains.
Apart from the usual scribble notes from the programmers there usually is a nice heap of papers containing physical model explanations, calculations and so on (equations, tables, graphs, little pictures describing variables ...)
We usually do numerically intensive calculations in console applications, which are not released to the public (remain in the house, only results go out). Before each project is finished all those papers have to be packed somehow with the application, so that one day, when someone will be reusing parts of it, has some idea what is what in there.
So far, we've been using the 'dirty' solution of just scanning all of it, and packing it up on the disc with the application.
So I was wondering ... for all science guys here in a similar situation ... how do you handle project documentation which is needed, but not released to the public ?
(the one that does, goes to the dtp laddies, and they make it nice and shiny - not our problem anymore :)
I use one of three options:
Keep everything in my lab notebooks, which I archive myself, for low-level stuff
Scan the paper document, and add to source control in pdf. It's ugly, but if someone needs it, it's there
Transcribe the equations, results, etc... in a clean format (usually Latex) for future reference, and again, add to source control. Official paper copy gets signed (I work in a highly regulated domain) and filed in a binder.
In the projects I've worked on we have done a lot of physics calculations in our programs and consequently we have a lot of whiteboard sessions with equations we are working on.
We keep a wiki for each major project and after each whiteboard session we physically photograph the whiteboard with a digital camera and upload/organize it within the wiki. We also scan in paper documents from developers notebooks if it is important and include it in the wiki as well.
Then, we back up the wiki on disc for storage. So our solution is pretty similar to yours, other than we use the project wiki for organization.
If it's important, it seems to me you should treat the internal documentation with the same care with which you treat the public docs.
I create UI paper prototypes when designing the UI of an application, which produces lots of A3-sized papers (in one project we had many desks covered with papers). When the design is ready or it needs to be mailed to somebody, I take pictures of it with a digital camera, so that I can produce a series of pictures showing how to perform some tasks on the UI, which serves as documentation of how the application is meant to work. This serves also as a backup, in case somebody steals/cleans away the original papers.
Here is some of the thoughts... Not so practical though :)
We can make it part of our Check-in notes. This may help the developers going to maintain the application.
Update the requirement document/Low level design document with these items
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 4 years ago.
Improve this question
In the course of your software development lifecycle, what essential design artifacts do you produce? What makes them essential to your practice?
The project I'm currently on has been in production for 8+ years. This web application has been actively enhanced and maintained over that time. While we have CMMI based policies and processes in place, with portions of our practice being well defined, the design phase has been largely overlooked. Best practices, anyone?
Having worked on a lot of waterfall projects in the past and a lot of adhoc and agile projects more recently, there's a number of design artifacts I like to create although I can't state enough that it really depends on the details of the project (methodology/team structure/timescale/tools etc).
For a generic, server-based 'enterprise application' I'd want the bare minimum to be something along these lines:
A detailed functional design document (aka spec). Generally something along the lines of Joel s' WhatsTimeIsIt example spec, although probably with some UML use-case diagrams.
A software techical design document. Not necessarily detailed for 100% system coverage but detailed in all the key areas and containing all the design decisions. Being a bit of an UML freak it'd be nice to see lots of pictures along the lines of package diagrams, component diagrams, key feature class diagrams, and probably some sequence diagrams thrown in for good measure.
An infrastructure design document. Probably with UML deployment diagram for the conceptual deisng and perhaps a network diagram for something more physical.
When I say document any of the above might be broken down into multiple documents, or perhaps stored on a wiki/some other tool.
As for their usefulness, my philosophy has always been that a development team should always be able to hand over an application to a support team without having to hand over their phone numbers. If the design artifacts don't clealry indicate what the application does, how it does it, and where it does it then you know the support team are going to give the app the same care and attention they would a rabid dog.
I should mention I'm not vindicating the practice of handing software over from a dev team to a support team once it's finished, which raises all manner of interesting issues, I'm just saying it should be possible if the management so desired.
Working code...and whiteboard drawings.
:P
Designs change so much during development and afterwards that most of my carefully crafted documents rot away in source control and become almost more of a hindrance than a help, once code is in production. I see design documents as necessary to good communication and to clarify your thinking while you develop something, but after that it takes a herculean effort to keep them properly maintained.
I do take pictures of whiteboards and save the JPEGs to source control. Those are some of my best design docs!
In our model (which is fairly specific to business process applications) the design artefacts include:
a domain data model, with comments on each entity and attribute
a properties file listing all the modify and create triggers on each entity, calculated attributes, validators and other business logic
a set of screen definitions (view model)
However do these really count as design artefacts? Our framework is such that these definitions are used to generate the actual code of the system, so maybe they go beyond design.
But the fact that they serve double duty is powerful because they are, by definition, up to date and synchronised with the code at all times.
This is not a design document, per se, but our unit tests serve the dual purpose of "describing" how the code they test is supposed to function. The nice part about this is that they never get out of date, since our unit tests must pass for our build to succeed.
I don't think anything can take the place of a good old fashioned design spec for the following reasons:
It serves as a means of communicating how you will build an application to others.
It lets you get ideas out of your head so you don't worry about tracking a million things at the same time.
If you have to pause a project and return to it later you're not starting your thought process over again.
I like to see various bits of info in a design spec:
General explanation of your approach to the challenge at hand
How will you monitor your application?
What are the security concerns and how are they addressed?
Flowcharts / sequence diagrams
Open issues
Known limitations
Unit tests, while a fantastic and arguably critical item to include in your application development, don't cover all of these topics.