On Fri, Mar 26, 2021 at 04:44:25PM +0000, Peter Maydell wrote: > On Fri, 26 Mar 2021 at 16:33, John Snow <js...@redhat.com> wrote: > > Being less terse about it: Mostly, I don't like how it enforces this > > column width even for indented structures. Generally, we claim that 72 > > columns is "comfortable to read" and I agree. > > > > However, when we start in a margin, I > > am not convinced that this is > > actually more readable than the > > alternative. We aren't using our full > > 72 characters here. > > I agree, and I don't see any strong reason to hold our Python > code to a different standard to the rest of our codebase as > regards line length and comment standards.
There's one small difference with python vs the rest of the codebase when it comes to API doc strings specifically. eg we have a docstring API comment in python/qemu/machine.py: class QEMUMachine: """ A QEMU VM. Use this object as a context manager to ensure the QEMU process terminates:: with VM(binary) as vm: ... # vm is guaranteed to be shut down here """ This formatting, including line breaks, is preserved as-is when a user requests viewing of the help: >>> print(help(qemu.machine.QEMUMachine)) Help on class QEMUMachine in module qemu.machine: class QEMUMachine(builtins.object) | QEMUMachine(binary: str, args: Sequence[str] = (), wrapper: Sequence[str] = (), name: Optional[str] = None, test_dir: str = '/var/tmp', monitor_address: Union[Tuple[str, str], str, NoneType] = None, socket_scm_helper: Optional[str] = None, sock_dir: Optional[str] = None, drain_console: bool = False, console_log: Optional[str] = None) | | A QEMU VM. | | Use this object as a context manager to ensure | the QEMU process terminates:: | | with VM(binary) as vm: | ... | # vm is guaranteed to be shut down here | | Methods defined here: | IOW, while we as QEMU maintainers may not care about keeping to a narrow line width, with API docstrings, we're also declaring that none of the users of the python APIs can care either. These docstrings are never reflowed, so they can end up wrapping if the user's terminal is narrow which looks very ugly. So this python API docstring scenario is slightly different from our main codebase, where majority of comments are only ever going to be seen by QEMU maintainers, and where C API doc strings don't preserve formatting, because they're turned into HTML and re-flowed. Having said all that, I still don't think we need to restrict ourselves to 72 characters. This is not the 1980's with people using text terminals with physical size constraints. I think it is fine if we let python docstrings get larger - especially if the docstrings are already indented 4/8/12 spaces due to the code indent context, because the code indent is removed when comments are displayed. I think a 100 char line limit would be fine and still not cause wrapping when using python live help(). Regards, Daniel -- |: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|