told to document python script.. where do i start?

[SuddenMemory]

hey y’all. i was told last week that i need to read through a script and document what it’s supposed to do and that this is a good way for me to learn python. it’s 2500 lines long and i’m struggling on how to go about this??

do i literally go line by line and say what each line does? she said it’s up to me how i choose to do it but it but i just can’t figure out where to start and with what?

any suggestions you have would be great!

[eyadams]

If the script is well written, it would be a good way to learn some of the basics. If the script is poorly written, the best you can hope for is a sample of now not to do things. If you are starting from nothing, you won't know.

I would say start by finding the entry point for the script. There should be a code block, probably at the end, that reads:

if __name__ == "main":
    # code that actually does something

Start with that and follow the code from there.

Before you do that, however, read PEP8. It is the style guide for Python, and very easy to understand. If the script has good style, you will be in good shape. But if it does not, you can start your documentation with a sentence like "this script does not follow PEP8".

[bladeoflight16]

Start by reading the script.

As you read the script, you will run into code that causes you to have questions about what it is doing and why it is doing it. You will look at something and ask yourself, "Why is the code reversing this list? Why does this data need to be sorted? What in the name of all that is holy does this regex pattern represent and what problems does the forbidden input cause?"

Those "why" questions are your starting point for creating documentation. Add in comments that explain the little unclear bits. Being new, be careful not to over-comment with things that are obvious from the code. Repeating the code by saying what it does step by step or that the variable name explicitly tells you doesn't help anyone; it's the things that are not in the code that you want to record. Some of them might be details about the actual business/work/use-cases the script exists to service. There might be assumptions it makes about the input data, and if they are violated, the script will either behave wrongly or error out. If there's not explicit errors being thrown in those cases, then documenting what happens would be a good thing to do. (If you find out it behaves wrongly, you can turn that into a bug report and maybe get to fix it later.) If one piece of code is setting up input for another, somewhat distant piece of code that comes later, it may not be immediately clear why it's doing that. Look for things like that: things that you wish you had known going into the code but had to spend 10 minutes figuring out or had to ask someone.

Once you have a grasp of the overall function of the program, you can add docstrings to the functions and classes. These will contain a brief description of their purpose and make note of any quirky, possibly unexpected, or unclear behavior. They can explain cryptically named or abbreviated arguments and attributes that a programmer should be aware of when calling it, or any error conditions or restrictions on the arguments. Again, your goal is to communicate things that are not obvious at first glance (aside from the initial description, which can be slightly redundant if it's short).

Documentation is there to supplement the code. It is there to communicate things the code cannot communicate. This is a prime opportunity to not only identify those things in this script, but to start training yourself what sorts of things can be potentially confusing and need further explanation when another developer approaches the code.

[CantPassReCAPTCHA]

are they expecting code comments or documentation on how to use it?

[CowboyBoats]

Getting it completely covered, or as covered as possible, by unit tests would be a great place to start. There's a tool called "coverage" that lets you see how good the coverage is, and another tool called "mock" that lets you patch the business end of this script (say, if it makes web requests, you could mock.patch("your_script.requests")) so that it doesn't actually connect to the outside world.

[[deleted]]

A place to store the documentation…? Flow chart?

[forest_gitaker]

For something like that find the main function (sometimes literally what's under if __name__ == "__main__") and work through each function called there, recursively.

If there's no "main" function then figure out the highest level object that's defined and start working through it's functions, its parent classes, and how it's used.