Thread: When to use COMMENT vs --

When to use COMMENT vs --

From
Rich Shepard
Date:
   I have used '-- ' to enter comments about tables or columns and am curious
about the value of storing comments in tables using the COMMENT key word.
When is the latter more appropriate than the former?

TIA,

Rich


Re: When to use COMMENT vs --

From
Pavel Stehule
Date:


2016-12-07 16:57 GMT+01:00 Rich Shepard <rshepard@appl-ecosys.com>:
  I have used '-- ' to enter comments about tables or columns and am curious
about the value of storing comments in tables using the COMMENT key word.
When is the latter more appropriate than the former?

Description entered with COMMENT statements is persistently saved in database system catalogue - see table pg_description. You can get the comment for any database object.

Comments like '--' or '/* ... */ are comments in source code, and they are just ignored in processing.

Regards

Pavel
 

TIA,

Rich


--
Sent via pgsql-general mailing list (pgsql-general@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-general

Re: When to use COMMENT vs --

From
Karsten Hilbert
Date:
On Wed, Dec 07, 2016 at 07:57:54AM -0800, Rich Shepard wrote:

>   I have used '-- ' to enter comments about tables or columns and am curious
> about the value of storing comments in tables using the COMMENT key word.
> When is the latter more appropriate than the former?

"--" only means "comment" to SQL code (such as in scripts).
PostgreSQL itself simply ignores it.

OTOH, using "comment on ... is ..." tells PostgreSQL to
_store_ a comment on a database object for later retrieval.

Karsten
--
GPG key ID E4071346 @ eu.pool.sks-keyservers.net
E167 67FD A291 2BEA 73BD  4537 78B9 A9F9 E407 1346


Re: When to use COMMENT vs --

From
John McKown
Date:
On Wed, Dec 7, 2016 at 9:57 AM, Rich Shepard <rshepard@appl-ecosys.com> wrote:
  I have used '-- ' to enter comments about tables or columns and am curious
about the value of storing comments in tables using the COMMENT key word.
When is the latter more appropriate than the former?

TIA,

Rich

​-- is a comment which is like a language comment: it has _no_ effect on the program being compiled. Likewise -- ​
 
​is simply ignored. The value in a COMMENT is actually stored in the data base. For example:

tsh009=# comment on schema racf is 'Snapshot of z/OS RACF database via IRRDBU00 output';
COMMENT
tsh009=# \dn+
                                        List of schemas
  Name  |  Owner   |  Access privileges   |                    Description                     
--------+----------+----------------------+----------------------------------------------------
 dasd   | tsh009   |                      | 
 junk   | tsh009   |                      | 
 public | postgres | postgres=UC/postgres+| standard public schema
        |          | =UC/postgres         | 
 racf   | tsh009   |                      | Snapshot of z/OS RACF database via IRRDBU00 output
 tape   | tsh009   |                      | 
 tmc    | tsh009   |                      | 
(6 rows)




--
Heisenberg may have been here.


Maranatha! <><
John McKown

Re: When to use COMMENT vs --

From
Chris Travers
Date:

On Dec 7, 2016 5:07 PM, "Karsten Hilbert" <Karsten.Hilbert@gmx.net> wrote:
>
> On Wed, Dec 07, 2016 at 07:57:54AM -0800, Rich Shepard wrote:
>
> >   I have used '-- ' to enter comments about tables or columns and am curious
> > about the value of storing comments in tables using the COMMENT key word.
> > When is the latter more appropriate than the former?
>
> "--" only means "comment" to SQL code (such as in scripts).
> PostgreSQL itself simply ignores it.
>
> OTOH, using "comment on ... is ..." tells PostgreSQL to
> _store_ a comment on a database object for later retrieval.
>

This also means that tools like pg_autodoc can include it as part of the generated documentation.
> Karsten
> --
> GPG key ID E4071346 @ eu.pool.sks-keyservers.net
> E167 67FD A291 2BEA 73BD  4537 78B9 A9F9 E407 1346
>
>
> --
> Sent via pgsql-general mailing list (pgsql-general@postgresql.org)
> To make changes to your subscription:
> http://www.postgresql.org/mailpref/pgsql-general

Re: When to use COMMENT vs --

From
"Charles Clavadetscher"
Date:
Hi Rich

> -----Original Message-----
> From: pgsql-general-owner@postgresql.org [mailto:pgsql-general-owner@postgresql.org] On Behalf Of Chris Travers
> Sent: Mittwoch, 7. Dezember 2016 17:12
> To: Postgres General <pgsql-general@postgresql.org>
> Subject: Re: [GENERAL] When to use COMMENT vs --
>
> On Dec 7, 2016 5:07 PM, "Karsten Hilbert" <Karsten.Hilbert@gmx.net <mailto:Karsten.Hilbert@gmx.net> > wrote:
> >
> > On Wed, Dec 07, 2016 at 07:57:54AM -0800, Rich Shepard wrote:
> >
> > >   I have used '-- ' to enter comments about tables or columns and am
> > > curious about the value of storing comments in tables using the COMMENT key word.
> > > When is the latter more appropriate than the former?
> >
> > "--" only means "comment" to SQL code (such as in scripts).
> > PostgreSQL itself simply ignores it.
> >
> > OTOH, using "comment on ... is ..." tells PostgreSQL to _store_ a
> > comment on a database object for later retrieval.
> >
>
> This also means that tools like pg_autodoc can include it as part of the generated documentation.

All of the relevant differences have been mentioned by previous posters. IMHO the fact mentioned by Chris Travers that
commentson objects included in the database can be used by tools to generate the documentation is probably the most
important(besides their being persisted). As a matter of fact we have integrated this feature to extract comments to
generatethe DB documentation in our internal MediaWiki based wiki. 

If you are interested in more details on that, including additional reasons why it is a good idea to use "comments on"
insteadof comments in the source code, you may have a look at this presentation: 


http://www.schmiedewerkstatt.ch/documents/04-publications/integrating_postgresql_documentation_in_3rd_party_applications_handout_pdfa.pdf

Bye
Charles

> > Karsten
> > --
> > GPG key ID E4071346 @ eu.pool.sks-keyservers.net
> > <http://eu.pool.sks-keyservers.net>
> > E167 67FD A291 2BEA 73BD  4537 78B9 A9F9 E407 1346
> >
> >
> > --
> > Sent via pgsql-general mailing list (pgsql-general@postgresql.org
> > <mailto:pgsql-general@postgresql.org> ) To make changes to your subscription:
> > http://www.postgresql.org/mailpref/pgsql-general
>




Re: When to use COMMENT vs --

From
Rich Shepard
Date:
On Thu, 8 Dec 2016, Charles Clavadetscher wrote:

> IMHO the fact mentioned by Chris Travers that comments on objects included
> in the database can be used by tools to generate the documentation is
> probably the most important (besides their being persisted).

Charles,

   Chris' contribution was the only one to answer my question.

> As a matter of fact we have integrated this feature to extract comments to
> generate the DB documentation in our internal MediaWiki based wiki.

   I'm not sure this is applicable to me. One project is for my business use,
the other for clients who will see only the entire application.

Thanks for explaining,

Rich


Re: [GENERAL] When to use COMMENT vs --

From
Merlin Moncure
Date:
On Wed, Dec 7, 2016 at 9:57 AM, Rich Shepard <rshepard@appl-ecosys.com> wrote:
>   I have used '-- ' to enter comments about tables or columns and am curious
> about the value of storing comments in tables using the COMMENT key word.
> When is the latter more appropriate than the former?

Main advantage of COMMENT is that the comments are transferred to the
database such that the comments will be made available to client tools
(like psql) and external programs.  For example, if you are generating
database diagrams out of the database automatically (which is a good
idea) with a good tool (I recommend SchemaSpy) the comments will
become visible.

Code style comments OTOH will decorate the file.  This is good if you
maintain your code as proper code, checking it into git and such,
which is also a very good idea.

Personally I tend to avoid COMMENT on aesthetics; I just dislike the
COMMENT section to *after* the object being created in code. If I had
a hypothetical "COMMENT ON NEXT OBJECT 'This is ...';" I would
probably use COMMENT a lot more :-).

merlin