1

My team writes a lot of Python code in PyCharm to do quick simulations and calculations for our mechanical engineering work. Often, we'd like to include a little image (a hand drawn sketch, CAD screenshot, or a PowerPoint slide with a diagram made from AutoShapes) to explain how different variables relate to a physical design. How might we effectively capture this information in comments?

8
  • 1
    I didn't down-vote but usually, it's to just write better code that doesn't need the comments/daigrams. Now, system architecture diagrams can be useful for communicating large scale information that can't be summarized well as code, but they're absolutely not for the granularity of tiny things like individual variables. The purpose of your variables should be obvious at a glance.
    – Alexander
    Jun 7 at 0:00
  • 1
    If you must include images in your code, put a web link to them in comments and host them on your SharePoint site (or whatever facility is convenient). Jun 7 at 2:52
  • 1
    You could use TempleOS :) or write in Microsoft Word :) besides that I don't think there is one. The best you can do is probably a hyperlink.
    – user253751
    Jun 7 at 9:06
  • 4
    @Alexander: you seem to have missed the fact that the OP is talking about mechanical engineering. Technical diagrams and scetches are the lingua franca of mechanical engineers. And if variables refer, for examples, to certain measures in an engineers drawing, you can only understand what they mean by seeing the related image side-by-side.
    – Doc Brown
    Jun 7 at 9:54
  • 1
    What Robert says: link to them using a URL or a file path to a network location. The remaining probem will be that links may break over time, this may or may not be an issue for you. If so, you can validate them automatically with a script in your CI environment. Jun 7 at 14:09

2 Answers 2

9

How might we effectively capture this information in comments?

You don't.

Comments are text, which is not a suitable replacement for images and scetches, especially not when these are technical engineer's drawings. Instead, choose an image format which most of your team members can handle and edit(!), then put the required scetches into your source tree (so they can be versioned together with the source code), and use comments to refer to those images.

Of course, typical image or CAD formats are binaries, or at least not very "diff"-friendly, but as long as they don't exceed a certain size, putting them under source control is usually the most pragmatic way.

4

My team writes a lot of Python code in PyCharm to do quick simulations and calculations for our mechanical engineering work.

Since it looks like the kind of code that you write (quick simulations and calculations) isn't full blown application code that these sorts of IDEs are designed for (as in, code for some application software that needs to be distributed and maintained), you might find tools used by data scientists / analysts better suited for the kinds of work that you do.

Look into Jupyter Notebook (or the newer JupyterLab) - it allows you to intersperse text, images and runnable Python code (code that can be executed right there in the notebook itself, it can generate outputs, diagrams, etc.) It's not as powerful as an IDE in terms of development features, but since you are primary dealing in mechanical engineering work, you might not be using many of those features anyway. Can't say for sure if this is what solves your needs, but it's worth checking out.

2
  • 1
    Jupyter is a great idea! Thank you!
    – Emily Conn
    Jun 7 at 16:26
  • 1
    Regarding"not as powerful as ide": You can also edit/view/run notebooks in IDEs including pycharm. Not sure how god's experience is, tho
    – RiaD
    Jun 7 at 21:38

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.