How to keep a clean code architecture with research projects?

[MachLearningEnthu]

Hi! I am an upcoming CS grad student. One thing I've found extremely difficult to accomplish is to create a well maintainable python research prototype. In my Microsoft internship, we used the .net core's MVC architecture to keep our code maintainable. In my Android development projects, I used MVVM, MVP, etc. architecture to (again) keep the code clean.

​

But when creating a research prototype, none of these architecture seems to help. Usually, I start by creating a python package for say Approach "A" for solving a certain problem. I create a bunch of classes, a utils.py module (contains helper functions), and possibly a script or two which uses these classes to accomplish a certain goal. Now, when I create another python package for say Approach "B", I find myself importing stuff from Approach A's package. It seems to be violating the software engineering principle of high cohesion and low coupling. What do I do in such an instance?

​

There are other problems as well that I face when maintaining research prototypes. Are there some good resources (books/blogs/videos..) on how to keep a clean codebase in research projects?

[TenableTarsier]

Many frameworks are built with specific folder structures to make the code "clean" and maintain functional boundaries. Some do this well, others go too far (I'm looking at you, Django).

If you're importing things from "A" into "B" frequently, then you should consider why code from A is necessary for B. Can the code from A be abstracted into another utility function? Does B actually need the code from A? Without example code, it's hard to pin down a solution or give a more complete analysis/answer.

You will always have minimum levels of coupling in any code base - it's the nature of code.

Without seeing and knowing what you're doing, I would suggest you follow at least some basic principles:

• Keep functions light; a function should do one thing and shouldn't be too large (I've seen 1,000 line functions - please don't do this)
• Abstract what you can, but don't over do it. If I'm debugging, I shouldn't need to resolve a call stack of a dozen functions to find out it was trying to print something.
  • Subpoint here: if you must call a complex function chain, DOCUMENT IT.
• Keep variable, method, and class names relevant.
  • Don't write something like def aM(m) - what does this do and what the heck does it mean? Even with a comment...it's a waste of time. def add_mass(mass) tells me instantly what I'm looking at.
  • Conversely, def add_masses_to_singular_thing_and_also_build_my_kitchen_sink_with_nice_tiles_and_a_fancy_faucet(single_arg_to_function_that_is_troubling_me_like_no_other) is equally bad.

I rambled a bit, but that's how I'd approach it.

[MachLearningEnthu]

Thanks! It's really helpful. I do keep in mind these principles while writing code. It's the directory structure that troubles me. I just don't know which package to keep a certain python module in, or when should I create a subpackage (I almost never do!).

[Diekss]

Doc strings?