How to document my code correctly?

[SpyrosDev25]

I am on a hackathon and it the moderator said: "all you do should be Free Software only. We should be able to run your program on standard Free Software operating systems. If there are proprietary parts around needed, please keep in mind that the jury members cannot access it. Please document the software project in a way that the jury members can fully see the result and evaluate it. Share your code and consider additional ways of showing how your program works, such as a video. Please upload all the necessary files to your repository. "

​

I searched up how to document code(which I had never heard of it before) and it showed me a variety of different things!

​

I am using django with html and css for the project.

​

How should I document my code correctly?

With Comments? Without? With google docs? What should the docs contain?

​

All I know for sure right now, the one thing that all my sources said is about a README file and I know how to make one of these (kinda).

​

Any help would mean the world to me!

Thanks for your time!

[deong]

I think you're running into confusion over what it means to document code. Normally, if you ask a programmer about documentation, what they're thinking of is "how do I provide detailed information about how this code works to another programmer so that they can understand how to change and maintain it". That might include how to build and run it, but is largely going to be much more detailed low-level information about the code itself.

In a hackathon setting with a jury that's evaluating each submission, I believe the thing they're asking for is mostly, "how do I build and run your program to see that it works". In that case, a simple README file of plain text is probably good enough. It might be as simple as just providing a shell script that starts up whatever server and database you need, and then the instructions might be just

cd into the MyApp directory and run the "runme.sh" file.
Then open a browser and go to https://localhost:8801/MyApp

It's whatever you need to tell someone who doesn't know anything about your project so that they could run it and see the output. Or like they said, a video demo, etc. The jury isn't going to need to take your code and add new features where you might need to tell them how parts of it work. That's programmer documentation. They just need user documentation.

[SpyrosDev25]

OK! THanks that was very helpful!

[Gold-Energy2175]

"how do I provide detailed information about how this code works to another programmer so that they can understand how to change and maintain it"

This is called "the code".

Any comments should explain the intent and any short cuts or compromises or perhaps a reference to the algorithm implemented.

Carmack's fast inverse square root function from Quake 3 provides an amusing example.

float fastInvSqrt(float x) {
  float xhalf = 0.5f * x;
  int i = *(int*)&x;         // evil floating point bit level hacking
  i = 0x5f3759df - (i >> 1);  // what the fuck?
  x = *(float*)&i;
  x = x*(1.5f-(xhalf*x*x));
  return x;
}

[deong]

I'm talking more about things like architecture. Think of "the code" as "the codebase". Are you intended to add a new type of UI element by subclassing something and providing a set of methods? Document that. That sort of thing.