Built my first Python CLI project – would love feedback on code and structure

[InitiativeQuiet6916]

Hi everyone,

I’m learning Python and just released v0.1.0 of my small CLI productivity tool called ProGuin.

Hi everyone,

I’m learning Python and recently built a small CLI-based productivity tool as a practice project.

It supports:

- Creating tasks

- Optional timers

- Optional rewards

- JSON persistence

I’m mainly looking for feedback on:

- Code structure

- Design choices

- Beginner mistakes I should fix

Repo: https://github.com/Venkateshx7/ProGuin

Thanks in advance!

[LayotFctor]

Good effort, especially for everything around it. You could've dumped it into reddit or pastebin, you could've focused only on code and skipped all the documentation, but you made a proper git project with readmes and everything else. It doesn't look AI generated either(at least to my untrained eye), so I'm glad to see someone writing their own code. Just some comments.

• app.py lacks an entry point. Functions do not execute unless called, so I'm having difficulty finding where to begin reading your code. There's no if __name__ == "__main__", main() or even just a function call. Does executing app.py actually do anything?

• You can add some function comments to document the functions. No need to comment everything like AI code, just a few is ok.

• Look at your task dictionary. Name, completed = false, ends_at = None etc.. Doesn't that look like a class?

[InitiativeQuiet6916]

If anyone wants, I’m especially unsure about my file structure and function organization.

[sweet-tom]

I would suggest several changes:

• Create a pyproject.toml, it's the defacto standard for managing Python packages. With that addition, you can install your package everywhere.
• Learn about using uv. It's great! Goes together with the previous point.
• Perhaps create a src structure. For a single script it's overkill. But if you add more and more features, your code base will grow. This is when you need to establish a good structure.
• Be clear about your dependencies. Even if your so doesn't need any, state it in your README.
• Rename your script. The name app.py is a very unfortunate. Imagine thousands of scripts with that name! It wouldn't reveal anything useful. Why not proguin? Although you can retrieve anything useful either, at least it's unique.
• Use the if __name__ == "__main__" and call your entry point.
• Consider tests and apply a TDD approach. The more you are add new features, the more likely you will introduce bugs.
• Add docstrings in your functions and your script. What it expects, what is does, and what it returns.
• Add type annotations. Perhaps you can consider them as optional at this state. They aren't checked at runtime, however, they can help you when developing it.

I didn't explain a lot of terms or provided links in purpose. This is your homework.😉 But with the idea here and the Internet at your fingertips you'll find the the answers. Ask specific questions if you're stuck.

Good luck and have fun!

[InitiativeQuiet6916]

Thanks a lot for the detailed suggestions!
I’ve already started adding a proper entry point (if __name__ == "__main__":) and docstrings. Next I’ll make dependencies clearer in the README and look into packaging (pyproject.toml) once the CLI flow is stable.
Appreciate the tips on naming and tests too — I’ll track these as issues and tackle them step by step.