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.
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 8 years ago.
Improve this question
I had recently stabilised developments of a major open source library written in Java. I have then published an article on the server side, which has brought me a lot of positive (but also critic, constructive) feedback. And a first contributor, which is great!
See the article here: http://www.theserverside.com/discussions/thread.tss?thread_id=61162
And the library: http://jooq.sourceforge.net
So with all of that good feedback, I have a great feeling about my project, in a way that I am creating something useful and original. Some key ideas behind my project, and why I think it is original:
It's an or-mapper. OK, now that really isn't original... ;-)
It has code generation in it. OK, still not original. But that's always nice.
It allows for creating type-safe queries in Java using its own domain specific language. That's better. No string concatenation. JPA has only just recently copied criteria queries from Hibernate.
It allows for doing so with all SQL features, including complex joins, nested selects, unions, aliasing, etc. Now that seems original to me. OR-mappers tend to try to ignore the relational data model behind RDBMS.
It supports all kinds of native non-standard functionality like UDTs, stored procedures, native functions, etc. I don't know any or-mapper that does that.
I think that these key ideas are useful for a very specific type of developer. That specific developer
interfaces Java with huge legacy databases.
knows SQL well and wants to use it extensively.
doesn't want to learn any new language (HQL, JPQL, etc)
doesn't want to spend one minute fine-tuning some sophisticated XML-configuration.
wants little abstraction over SQL, because his software is tightly coupled with his database. Something that I think the guys at Hibernate or JPA seem to have ignored.
EDIT: needs a strong but light-weight library for database access. For instance when they develop for mobile devices (see comment by SRM).
Now is the beginning of the hard work. How to get attention? How can I attain a bigger crowd? How can my project become relevant? How to reach to that "specific type of developer"?
I would say set up a professional looking site (one that doesn't look like it was designed by a 15 year old script kiddie). Make sure you have ample documentation with plenty of help and/or tutorials for using your library. Example applications are also good to see a real world usage of the library.
Once you have that setup I would do some typical SEO to drive traffic to your site. This includes blog articles, links back to your page and or articles, and possibly buying some Addwords from google.
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 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.
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 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 7 years ago.
Improve this question
Design patterns are great in that they distill a potentially complex technique into something idiomatic. Often just the fact that it has a name helps communication and understanding.
The downside is that it makes it easier to try to use them as a silver bullet, applying them to every situation without thinking about the motivation behind them, and taking a second to consider whether a given pattern is really appropriate for the situation.
Unlike this question, I'm not looking for design patterns that are often misused, but I'd love to see some examples of really solid design patterns put to bad use. I'm looking for cases where someone "missed the point" and either applied the wrong pattern, or even implemented it badly.
The point of this is that I'd like to be able to highlight that design patterns aren't an excuse to disable critical analysis. Also, I want to emphasise the need to understand not just what the patterns are, but why they are often a good approach.
I have an application that I maintain that uses a provider pattern for just about everything -- with little need. Multiple levels of inheritance as well. As an example, there's a data provider interface that is implemented by an abstract BaseDataProvider, that is in turn extended by a SqlDataProvider. In each of the hierarchies, there is only one concrete implementation of each type. Apparently the developer got ahold of a Microsoft document on implementing Enterprise Architecture and, because lots of people use this application, decided it needed all the flexibility to support multiple databases, multiple enterprise directories, and multiple calendering systems even though we only use MS SQL Server, Active Directory, and Exchange.
To top it all off, configuration items like credentials, urls, and paths are hard-coded all over the place AND override the data that is passed in via parameters to the more abstract classes. Changing this application is a lot like pulling on a thread in a sweater. The more you pull the more things get unraveled and you end up making changes all over the code to do something that should have been simple.
I'm slowly rewriting it -- partly because the code is awful and partly because it's really three applications rolled up into one, one of which isn't really even needed.
Well, to share a bit of experiance. In C#, I had a nicely cool design which used lots of pattern.. I really used lot of them so to make the story short, I won't name it all. But, when I actually tested with real data, the 10^6 objects didn't "run smoothly" with my beautiful design. And by profiling it, I just saw that all those indirection level of nicely polymorphisms classes, proxy, etc. were just too much.. so I guess I could have rewritten it using better pattern to make it more efficient but I had no time, so I practically hacked it procedurally and until now, well, it works way better.. sigh, sad story.
I have seen an asp.net app where the (then junior, now quite capable) developer had managed to effectively make his codebehinds singletons thinking each page was unique which worked brilliantly on his local machine right up to the point where the testers were fighting for control of the login screen.
Purely a misunderstanding of the scope of "unique" and a mind eager to use these design pattern thingies.