diff --git a/docs/tips.rst b/docs/tips.rst index f117e0aa..28430e65 100644 --- a/docs/tips.rst +++ b/docs/tips.rst @@ -1,6 +1,6 @@ -##################### -Tips & Best Practices -##################### +############################ +Tips, Best Practices and FAQ +############################ Although there are countless ways to create objects with build123d, experience has proven that certain techniques can assist designers in achieving their goals @@ -151,6 +151,7 @@ An example of where this my arise is with the thread of a screw (or any helical one complete revolution the part may contact itself. One is likely be more successful if the part is split into multiple sections - say 180° of a helix - which are then stored in an assembly. +.. rst-class:: clearfix ************************** Packing Objects on a Plane @@ -169,3 +170,26 @@ padding (right): .. image:: assets/packed_boxes_output.svg :align: right + + +.. _are_glob_imports_bad_practice: + +*********************************************** +Isn’t ``from build123d import *`` bad practice? +*********************************************** + +Glob imports like ``from build123d import *`` are generally frowned upon when writing software, and for +good reason. They pollute the global namespace, cause confusing collisions, and are not future-proof, as +future changes to the library being imported could collide with other names. It would be much safer to do +something like ``import build123d as bd`` and then reference every item with, for example, ``bd.BuildPart()``. +If your goal is to integrate build123d into a larger piece of software, which many people work on, or where +long-term maintainability is a priority, using this approach is definitely a good idea! Why, then, are +glob imports so often used in build123d code and official examples? + +build123d is most commonly used not as a library within a larger application, but as a `Domain-Specific Language `__ +which, together with something like the OCP CAD Viewer, acts as the user interface for a CAD application. +Writing build123d often involves live coding in a REPL or typing in editors with limited space due to +the rest of the CAD GUI taking up screen space. Scripts are usually centred around build123d usage, with +usage of other libraries being limited enough that naming conflicts are easily avoided. In this context, +it’s entirely reasonable to prioritise developer ergonomics over “correctness” by making build123d’s primitives +available in the global namespace. \ No newline at end of file diff --git a/docs/tutorial_lego.rst b/docs/tutorial_lego.rst index f079ec30..168b3d0f 100644 --- a/docs/tutorial_lego.rst +++ b/docs/tutorial_lego.rst @@ -14,7 +14,7 @@ Step 1: Setup Before getting to the CAD operations, this Lego script needs to import the build123d environment. There are over 100 python classes in build123d so we'll just import them -all with a ``from build123d import *`` but there are other options that we won't explore +all with a ``from build123d import *`` but :ref:`there are other options ` that we won't explore here. The dimensions of the Lego block follow. A key parameter is ``pip_count``, the length