Develop Reference

How to share code documentation for a project?

There was a similar-ish question here on SO https://stackoverflow.com/questions/9475795/how-do-you-share-code-across-teams-working-on-very-different-projects but mine is about writing documentation.
Scenario:
Let's say my team is working on a software project, a Fany-WordPad like application which has a feature called Fancy-Word-Art ( just like MS Office's word Art). Now I wrote the code for the main window( using WPF in .Net, or using Window Builder in Java, doesn't matter which tool/language).
Now if my colleague Mr Spongebob is writing the Word-Art part, how would I tell him what functions to call / Api to use to draw on my window? i.e. How do I let Mr SpongeBob know that he needs to call GetWindow() method to get a reference to the drawing surface, the parameters he needs to pass along , and so on?
I hope I am being clear here. Is this the procedure?
Step 1 : Use your company wiki site to understand your colleague's written code
Step 2 : Write the GetWindow() method so that it works well with the rest of the project
Step 2 : Now put a wiki on your intranet with the method parameters/ data type requirement for your GetWindow() method or use Doxygen/ Confluence as suggested below
Step 3 : Now its your colleague Mr Spongebob's headache how to find how to draw his word-art on my window.
This just doesnt sound right .. With tons of functions, Spongebob's life will be hard, just as mine. Both of us rummaging through documentation to find the right functions to do our job. What if then I change GetWindow() to GetWindow(string title).. Now how do I literally tell the poor spongebob he needs to redo his code.
Am I missing something here? Please share your experience, how do you tackle this problem in a real world software house environment? If your fellow developer is on the next table , do you actually show them how to implement a certain method as they get stuck, or how do you deal with this situation?
thank you
Thanks

A good question. Of course i do not have the universal solution. Code documentation in msdn/sun style is a good base. But for concepts, architecture and so one you need more than this. In some projects we use wikis for that. For customer requests, we have a kind of ticket-system where we also store some (no-code) information to solution. All in all there is no central place for all the documentaion stuff.
Edit: Your code in self is often the best documentation, following clean code guidelines or something else is a real best practice :-)

Wikis are a cracking idea (good suggestion #Micha!). I used to use one in a previous company for a large engineering software/hardware project. It obviously spanned hardware and software guys and so it was a great way to share info across all teams. It's really useful if it's a long term project too - you can keep track of changes to functionality/API as things inevitably morph over time.
We used a paid service - Confluence if I remember rightly; but there are free wiki hosting sites too e.g. wikihost (just a quick google search, I can't vouch for them).
On another note though - have you thought about self documenting code at all? For example "Doxygen" or similar? Takes a lot of pain out of documenting every single function and also sets up a decent framework that can be padded out with more info where necessary. It also creates a nice UI for stepping through all the functions /class etc.
Edit: I've actually just started using Google Sites (sites.google.com) to create a wiki for a dev team I'm not working with. It's free (as in 'beer') and seems pretty good so far, although it does lack auto code formatting.

IMO you need both API documentation and plenty of examples.
You might get some mileage out of documenting your code of course, but if you're truly writing a system properly, your clients will never see your code. (That goes for clients in the calling sense, not necessarily in the "paying for your services" sense).
That's a fundamental of good practice and SOA, so you should really discard the "self documenting code" approach.
An alphabetic list of functions/methods/properties/whatever has value once the client has "got it" but until then, it's not immediately useful.
So that leaves you with having to showcase your creation. Give a bunch of immediately useful examples that demonstrate the kind of thing you envisaged. Make sure you have a simple example that demonstrates every function in its basic form with minimal interaction with the rest of the system (too many required interactions and you've probably not got a clean system anyway).
Once you have that, put it on a Wiki and encourage your users to enhance it. Consider using something interactive like a Stack-Overflow-like platform. MSDN is a good model but their examples often suck and can lack context. You might have the luxury of having more tight and specific uses than, say, the entire .NET framework. Early response to questions and updates to your examples/documentation will ensure your message gets across in the vital early days. This will help your documentation burden tail off quickly by looking after your clients and giving them useful, practical help.
Hope that helps.

In my projects I use a short description in my class files at the top, like:
//======
//
// modul: fileRunner.cs
// ...
// what: for playing audio/video
// depends on: consoleOutput.cs (Form)
//
//=======
#region HowToUse
//=======
//
// HowToUse
//
// 1. create instance of fileRunner:
// fileRunner p = new fileRunner();
// 2. run console program [progPath] with arguments [cmdsString]
// string output = p.RunExternalExe(progPath, cmdsString);
// 3. handle [output]
// if (output == "anyError"){do something;}
//
// [OUTPUT]
// "0" : process ended w/o errors
// "C" : canceled by user
// else: output is the string of the StdError, the called program submitted + StdOut after "Std output:"
//
// IMPORTANT
// Mention, this file depends on consoleOutput.cs to parse the output for gui.
// It doesn't support input ways, because the way ffmpeg is outputting doesn't allow it, it's not active
//=======
#endregion
For other classes I just named the public functions, that are self-describing.
An other option is to write on the top that they should look an the comment in the code and on the top of the public functions I use similar explanations:
#region convert an audio or video file from a drop
// FUNCTION: convertTo
// DOES: converting a file from a drop
// does not delete the original
// INPUT1: [path] as string,
// path to the destination file
// INPUT2: [e] as System.Windows.Forms.DragEventArgs,
// the args, the drop-object submits
// path of source file is in here
// OUTPUT: isConverted as bool,
// true if not (canceled or error raised)
public bool convertTo(string pWorkingFile, DragEventArgs e)
{
...
}
#endregion
If something changes you can mention it at the top too.
I think with SCM software it's a good option to mention the most important w/o wasting too much time on documentation.

as Stupid as it sounds, I would write him (Spongebob) a mail, or just tell him what he will need. If you already know who will need something in the near future, it is great if you can inform those peope before they strat to search and get headaches. Not everything in a project needs a technical Solution very often a human to human is much better.
Your documentation can also be in a wiki and then you can simply send Spongebob a link.

To reduce the pain involved in changing specifications over a large api, I'd suggest you follow the msdn/javadoc convention as mentioned earlier and also advice your team mate to use a modern IDE with autocompletion/autosuggest feature. Most of the common editors that provide auto suggestion also display documentation for the method/member to be used.
If you are seeking agile here, then docs and wikis are slight overkill; my 2 cents.

Why don't you just put your work in one git/svn project instead of working on the project parts independently? Then when you change a core function, you will see what it breaks and be responsible for fixing the methods that call it before committing your changes.
I am not a big fan of documenting extensively during development. It slows you down too much and you will have to redo it over and over again. Just create descriptive method names and be generous with you in-code comments.

For starters:
To help the situation between spongebob and yourself working together you will need some sort of Code Asset Management software (GIT, TFS, etc).
What if then I change GetWindow() to GetWindow(string title).. Now how do I literally tell the poor spongebob he needs to redo his code.
You should always start your day coding by "GET LATEST", meaning download code from the repository. If spongebob does this he will immediately see that he now needs to pass in string title as his code will stop compiling. It would be preferable that you literally tell spongebob that you have changed your code and he now needs to pass in a value, but if you are both checking in code every night and getting latest when you start coding for the day you should be both informed.
As far as the use of a WIKI or if you use Sharepoint doesnt matter. I would say to make it a little more efficient why not do this:
In your document repository (Wiki/Sharepoint) call the files by the page name so one is WordArt, the other is MainDocument, maybe one is PrintDocument (assuming these are different pages) and in the code you can simply put:
For more information on this visit the ___site at :http://yourrespositoryname.com/nameofprocedure

Hook on compiler / Hook on the output of a method (C# - c++)

Well to start ill tell u what i have to do.
I have to make a program so students can upload some C++ code from an exercise. And this uploaded code needs to get compared with the "best code" from that exercise. And from those comparisation the server gives back some feedback if the student uploaded good or bad code.
EG: the Exercise is to make an arraylist from 1 to 10 and so the student can upload his code. The server then compares it with some other code and gives feedback.
This is easyer said then done, because it can't be just a file comparer because of the different variables a user can code. Thats why i was tinking of using external compilers to get some output and compare this output with the output of the "best code". Or more detailed to get a hook within the compiler so i can check every method and every variable.
Or any other idea how i can check this or compare?
Or is there already a program that exist?
Very thanks,
Michael

There are systems that assess the output of the whole program (like ejudge, it is used as a contest system), and, in my opinion, it's easier to use them, because specifying conditions on the program code is itself not a trivial task (if your students are writing non-trivial programs).
You can use formal specification languages like ACSL to set input and output conditions and prove that the program works correctly.

It might be more practical to evaluate the code by testing the behaviour against some automated tests, like a boundary test suite (or even a mutant test if you want things to get exciting), and then to look for odd implementations or interesting architectures look at code metrics like number of functions, lines of code, compile size, etc. .
This approach would be a lot more scalable, and there is a lot of free tools, especially for c++ and java that would be easy to set up an automated test system.
Comparing code to determine correctness is not necessarily a correct approach, depending on how it is done, and would be very difficult to scale up.

c# compile source code from database

I would like to build an application framework that is mainly interpreted.
Say that the source code would be stored in the database that could be edited by the users and always the latest version would be executed.
Can anyone give me some ideas how does one implement sth like this !
cheers,
gabor

In .Net, you can use reflection and CodeDOM to compile code on the fly. But neither approach is really very simple or practical. Mono has some ability to interpret c# on the fly as well, but I haven't looked closely at it yet.
Another alternative is to go with an interpreted .Net language like Boo or IronPython as the language for your database code.
Either way, make sure you think long and hard about the security of your platform. Allowing users to execute arbitrary code is always an exercise fraught with peril. It's often too tempting to look for a simple eval() method, and even if one exists, that is not good enough for this kind of scenario.

Try Mono ( http://www.monoproject.org ). It supports many scripting languages including JavaScript.

If you don't want to use any scripting you can use CodeDOM or Reflection (see Reflection.Emit).
Here are really useful links on the topic :
Dynamically executing code in .Net (Here you can find a tool which can be very helpul)
Late Binding and On-the-Fly Code
Generation Using Reflection in C#
Dynamic Source Code Generation and
Compilation

Usually the Program uses a scripting language for the scriptable parts, i.e. Lua or Javascript.

To answer your technical question: You don't want to write your own language and interpreter. That's too much work for you to do. So pick some other language, say Python or Lua, and look for the documentation that lets your C program hand it blocks of code to execute. Of course, the script needs to be able to do something, so you'll need to find how to expose your program's objects to the script. Also, what will happen if a client is running the program when you update its source code in the database? Should the client restart? Are you going to store the entire program as a single row in this database, or did you want to store individual functions? That affects how you structure your updates.
To address other issues with your question: Why do you want to do this? Making "interpreted language" part of your design spec for a system is not often a good sign. Is the real requirement something like this: "I update the program often and I want users to always have the latest copy?" If so, there are other, better ways to go about this (just give us your actual scenario and requirements).

If it is possible to auto-format code before and after a source control commit, checkout, diff, etc. does a company really need a standard code style?

If it is possible to auto-format code before and after a source control commit, checkout, diff, etc. does a company really need a standard code style?
It feels like standard coding style debates that have been raging since programming began like "put the bracket on the following line" or "properly indent your (" are no longer essential.
I realize in languages where white space matters the diff will have to consider it but for languages where the style is a personal preference is there really a need to worry about it anymore?

Auto-format can really only address whitespace.
It wont address developers giving variables bizarre nonsensical names.
It won't address some developers having functions return null on an error vs throwing an exception.
I'm sure others can think of more examples.

This is what we do at my work:
We all use Eclipse. We don't have a policy for using Eclipse but somehow none of us is an IDEA/IntelliJ guy. We also think our code should be written with legacy in mind. This means our code has to be readable in a certain way even years after (#1) no matter who wrote it and if that person even is in the company anymore.
Eclipse has couple handy features, automatic format on save and a specific Formatter tool. As you can see from the linked screenshot, it can be configured with XML. Thus there's a bunch of premade XML:s available for every worker in our company so that when a new guy comes in, we walk him through of the whole process and configure their Eclipse for them (yes, it's slightly evil thing to do) so that it actually uses those formatting XML:s we have provided. We do not enforce automatic format on save, we don't want to be completely intrusive, we just want to push all our developers into the right directions. For even increased compatability, we mostly use rules defined in JCC.
Next comes the important part, the actual builds. We are those who embrace automatic builds and for that we use Hudson Continuous Integration Server. There's two important parts in our configurations beyond this:
We use CVS loginfo to trigger builds whenever something is committed.
We utilize several plugins available for Hudson, including Continuous Integration Game in conjuction with the most important one, Checkstyle.
The Checkstyle Plugin is the magician in our code style enforcement guide line:
After commiting code to CVS, Hudson build is triggered
After build has been completed succesfully (all unit tests pass etc.), Checkstyle inspects the actual source files
Checkstyle ranks the code based rules we have defined for it
Continuous Integration Game sees the result of Checkstyle and awards/takes away points for the person who has the ownership for the relevant part of the code
Leaderboard shows total points for every commiter in system
Basically this means that when anyone commits ugly code into our CVS, our build server automatically reduces that person's points.
This means that eventually any one of us can be ranked on the Leaderboard based on the general code quality in both look and OO principles such as Law of Demeter, Cyclomatic complexity etc. etc. Naturally this isn't a completely serious statistic, but it's a good indication you're doing something wrong when causing a build to be initiated in our CI won't reduce your points - most of our commits are worth between 1 and 5 points.
And is it working? Sort of, I don't think anyone of us at my work writes ugly or unmaintainable code and personally I love to hunt all kinds of scores so it's definitely motivating me to make code that looks nice and follows all the OO paradigms I know of.
And do we as a company really need it? I think we do as you should see from reading this entire answer, it can be considered a good practice for the advancements it brings.
#1: in a related note, I refactored legacy code from 2002 today which used those standards, didn't look "bad" at all even in its original form and certainly not worse in its new form

No, not really.
If you can actually get it to work consistently and not make it flag code has changed due to a different style of laying the code out.
However, this is just a small part of coding standards. It won't cover multiple return statements, the use or not of ternary operators, etc.

It is always nice if the coding style that the shop uses is the same one that is also followed by the development tools.
Otherwise, if there is a large body of code that already follows a shop standard which is NOT the same as that of the tools you have two choices:
Modify all of the code to follow the tool standard, or
Maintain the existing shop standard.
Many shops do the latter. Regardless, there does need to be some kind of standard, and it does need to be followed.
Some development tools allow you to tweak their standard. In some cases you may be able to bring the tools in alignment with the shop standard.

It probably doesn't matter that much anymore if you can ensure that everybody in the team sees the source code "correctly" formatted, whatever they think it is. However I've not seen a system that can do that - you can do parts of it (say, reformat before and after checkin/checkout) but these days you also have to consider web interfaces into the version control, external code review systems that interact directly with the version control system etc.
The main purpose of a standard code style is (IMHO) to ensure that you can read other team members' code easily without having to start reverse engineering it because all the code is written using the same sort of guiding principles. Indenting and parentheses placement seem to be a major hangup on this but they are only a very small and in my opinion, somewhat overblown and not very important part of the need to make code consistent.
Unfortunately I'm not aware of any tools that can automatically apply consistent coding principles to source code...

Yes, coding styles are needed if there is a desire to have a homogeneous code base. Such a code base can be useful in preventing individual ownership of parts of the code base, which can cause problems when people leave the team. If you can't imagine having wildly different styles and problems understanding all of it, just look at all the different ways English text can be organized in various communications, all written but quite different such as tweets, e-mail, text messages, IM, message board posts, etc. and changes in fonts, capitalization, decorations, etc.

Encrypt my framework and code

i am creating my own CMS frame work, because many of the clients i have, the have same requirements, like news module, newsletter module, etc.
now i am doing it fine, the only thing that is bothering me, is if a client wants to move from my server he would ask me to gibe him his files, and of course if i do so the new person who will take it he will see all my code, use it and benefit from i, and this is so bad for me that i spend all this time on creating my system and any one can easily see the code, plus he will see all the logic for my system, and he can easily know how other clients of mine sites are working, and that is a threat to me, finally i am using third party controls that i have paid for their license, and i don't want him to take it on a golden plate.
now what is the best way to solve this ? i thought it is encrypting, but how can i do that and how efficient is it ?
-should i merge all my CS files and Dlls in bin folder to one Dll and encrypt it, and how can i do that ?
i totally appreciate all the help on this matter as it is really crucial for me.

you should read this
Best .NET obfuscation tools/strategy
How effective is obfuscation?

In my experience, this is rarely worth the effort. Lots of companies who provide libraries like this don't bother obfuscating their code (Telerik, etc).
Especially considering what you are writing (CMSes are everywhere), you'd likely see more benefit from your time spent implementing features that put your product/implementation in a competitive advantage and make companies see that the software you are capable of writing has value, rather than the code itself.
In the end, you want to ensure you are a key factor in making software work for a company, not the DLLs you give them.

You'll need to precompile your site and obfuscate dlls.
Visual Studio has something like Dotfuscator Community Edition shipped with it. You could give it a try.
Of course, HTML output, CSS declarations, database structure and stored procedures code cannot be encrypted.
You can however try to compress CSS which will also reduce its readbility by humans.
Check here: The best approach to scramble CSS definitions to a human-unreadable state throughout an ASP.NET application
One other idea would be to use a frame in your HTML and put the most of the site pages inside of it. This way, it will not be visible when doing "View source".
Or just state it clearly that you offer whatever you're doing as a service and do not provide source codes of your work. I somehow doubt salesforce would be willing to give their sources to anyone who asks.